From 5555b74650a32faaad221e83c14bdf1cef6d85e7 Mon Sep 17 00:00:00 2001
From: Stephanie Hobson <sjhobson@gmail.com>
Date: Wed, 31 Jul 2024 14:28:43 -0700
Subject: [PATCH] Convert buttons with data-link-type="download" into CTAs Fix
 #14062

---
 bedrock/base/templates/macros.html            | 18 ++++-
 .../firefox/browsers/chromebook.html          |  4 +-
 .../includes/download-button-thanks.html      |  2 +-
 .../firefox/includes/download-button.html     |  5 +-
 .../firefox/includes/download-list.html       |  2 +-
 .../templates/firefox/includes/macros.html    | 17 ++++-
 docs/attribution/0001-analytics.rst           | 72 +++++++++++++++++++
 7 files changed, 109 insertions(+), 11 deletions(-)

diff --git a/bedrock/base/templates/macros.html b/bedrock/base/templates/macros.html
index 8b156268b6b..49ec1a191b6 100644
--- a/bedrock/base/templates/macros.html
+++ b/bedrock/base/templates/macros.html
@@ -48,7 +48,14 @@
 {% macro google_play_button(class_name='', extra_data_attributes={}, extra_img_attributes={}, href=settings.GOOGLE_PLAY_FIREFOX_LINK_UTMS, id='', product='Firefox', target='') -%}
 {% set optional_img_attributes = {'alt': ftl('download-button-google-play'), 'width': '152', 'height': '45', 'l10n': True} %}
 {% do optional_img_attributes.update(extra_img_attributes) %}
-<a class="ga-product-download {{ class_name }}"{% if id %} id="{{ id }}"{% endif %}{% if target %} target="{{ target }}" rel="external noopener noreferrer"{% else %} rel="external"{% endif %} href="{{ href }}"{% if product in ['Firefox', 'Focus'] %} data-link-type="download" data-cta-type="firefox_mobile"{% endif %}{% for attr, val in extra_data_attributes.items() %} data-{{ attr }}="{{ val }}"{% endfor %}>
+<a class="ga-product-download {{ class_name }}"
+    {% if id %}id="{{ id }}"{% endif %}
+    {% if target %}target="{{ target }}" rel="external noopener noreferrer"{% else %} rel="external"{% endif %}
+    href="{{ href }}"
+    data-cta-text="Play Store"
+    {% if product in ['Firefox'] %}data-cta-type="firefox_mobile"{% elif product in ['Focus', 'Klar'] %}data-cta-type="firefox_focus"{% endif %}
+    {% for attr, val in extra_data_attributes.items() %} data-{{ attr }}="{{ val }}"{% endfor %}
+    >
   {{ resp_img(
     url='img/firefox/android/btn-google-play.png',
     srcset={
@@ -61,7 +68,14 @@
 
 {% macro apple_app_store_button(class_name='', extra_data_attributes={}, extra_img_attributes={}, href=settings.APPLE_APPSTORE_FIREFOX_LINK, id='', product='Firefox', target='') -%}
 {% set optional_img_attributes = {'width': '152', 'height': '45'} %}
-<a class="ga-product-download {{ class_name }}"{% if id %} id="{{ id }}"{% endif %}{% if target %} target="{{ target }}" rel="external noopener noreferrer"{% else %} rel="external"{% endif %} href="{{ href }}"{% if product in ['Firefox', 'Focus'] %} data-link-type="download" data-cta-type="firefox_mobile"{% endif %}{% if product == 'Firefox' %} {% endif %}{% for attr, val in extra_data_attributes.items() %} data-{{ attr }}="{{ val }}"{% endfor %}>
+<a class="ga-product-download {{ class_name }}"
+    {% if id %} id="{{ id }}"{% endif %}
+    {% if target %} target="{{ target }}" rel="external noopener noreferrer"{% else %} rel="external"{% endif %}
+    href="{{ href }}"
+    data-cta-text="App Store"
+    {% if product in ['Firefox'] %}data-cta-type="firefox_mobile"{% elif product in ['Focus', 'Klar'] %}data-cta-type="firefox_focus"{% endif %}
+    {% for attr, val in extra_data_attributes.items() %} data-{{ attr }}="{{ val }}"{% endfor %}
+    >
   <img src="{{ l10n_img('firefox/ios/btn-app-store.svg') }}" alt="{{ ftl('download-button-download-app-store') }}"{% for attr, val in optional_img_attributes.items() %} {{ attr }}="{{ val }}"{% endfor %}>
 </a>
 {%- endmacro %}
diff --git a/bedrock/firefox/templates/firefox/browsers/chromebook.html b/bedrock/firefox/templates/firefox/browsers/chromebook.html
index 065dbddcccc..9419bf8ee63 100644
--- a/bedrock/firefox/templates/firefox/browsers/chromebook.html
+++ b/bedrock/firefox/templates/firefox/browsers/chromebook.html
@@ -49,13 +49,13 @@ <h1 class="mzp-u-title-xl">{{ ftl('browsers-chromebook-get-firefox-browser') }}<
     <h4 class="mzp-c-menu-list-title">{{ ftl('browsers-chromebook-dropdown-copy') }}</h4>
     <ul class="mzp-c-menu-list-list download-platform-list">
       <li class="mzp-c-menu-list-item">
-        <a href="{{ android_url }}" rel="external noopener" class="ga-product-download" data-link-type="download" data-display-name="Android" data-download-version="android" data-cta-type="firefox_mobile">
+        <a href="{{ android_url }}" rel="external noopener" class="ga-product-download" data-download-version="android" data-cta-text="Get Firefox for Android" data-cta-type="firefox_mobile" >
           {{ ftl('browsers-chromebook-browsers-chromebook-get-firefox-for') }}
           <p><small>{{ ftl('browsers-chromebook-x86-based-chromebook') }}</small></p>
         </a>
       </li>
       <li class="mzp-c-menu-list-item t-sumo">
-        <a href="https://support.mozilla.org/kb/run-firefox-chromeos?utm_source=www.mozilla.org-firefox-browsers-chromebook&amp;utm_medium=referral&amp;utm_campaign=seo" rel="external noopener" data-cta-text="Install Firefox for Chromebook" data-cta-type="link">
+        <a href="https://support.mozilla.org/kb/run-firefox-chromeos?utm_source=www.mozilla.org-firefox-browsers-chromebook&amp;utm_medium=referral&amp;utm_campaign=seo" rel="external noopener" data-cta-text="Install Firefox for Chromebook">
           {{ ftl('browsers-chromebook-get-firefox-desktop') }}
         </a>
       </li>
diff --git a/bedrock/firefox/templates/firefox/includes/download-button-thanks.html b/bedrock/firefox/templates/firefox/includes/download-button-thanks.html
index 1520b8859f5..c3a07d5c3c2 100644
--- a/bedrock/firefox/templates/firefox/includes/download-button-thanks.html
+++ b/bedrock/firefox/templates/firefox/includes/download-button-thanks.html
@@ -8,8 +8,8 @@
   <a href="{{ transition_url }}"
      class="download-link c-button-download-thanks-link mzp-c-button mzp-t-product {% if button_class %}{{ button_class }}{% else %}mzp-t-xl{% endif %}"
      data-direct-link="{{ download_link_direct }}"
-     data-link-type="download"
      data-testid="{{ id }}"
+     data-cta-text="Download Firefox"
      {% if download_location %}data-cta-position="{{ download_location }}"{% endif %}>
     {% if alt_copy %}
       {{ alt_copy }}
diff --git a/bedrock/firefox/templates/firefox/includes/download-button.html b/bedrock/firefox/templates/firefox/includes/download-button.html
index 8a35846f844..bed229b6365 100644
--- a/bedrock/firefox/templates/firefox/includes/download-button.html
+++ b/bedrock/firefox/templates/firefox/includes/download-button.html
@@ -21,8 +21,8 @@
       {% for plat in builds -%}
         <li><a href="{{ plat.download_link_direct or plat.download_link }}"
                class="download-link mzp-c-button mzp-t-product ga-product-download"
-               data-link-type="download"
                data-download-version="{{ plat.os }}"
+               data-cta-text="Download Firefox for {{ plat.os_arch_pretty or plat.os_pretty }}"
                {% if plat.os == 'android' %}data-cta-type="firefox_mobile"
                {% elif plat.os == 'ios' %}data-cta-type="firefox_mobile"
                {% else %}data-cta-type="firefox"{% endif %}>{{ plat.os_arch_pretty or plat.os_pretty }}</a>
@@ -61,9 +61,8 @@
            id="{{ id }}-{{ plat.os }}"
            href="{{ plat.download_link }}"{% if plat.download_link_direct %}
            data-direct-link="{{ plat.download_link_direct }}"{% endif %}
-           data-link-type="download"
-           data-display-name="{{ plat.os_arch_pretty or plat.os_pretty }}"
            data-download-version="{{ plat.os }}"
+           data-cta-text="Download Firefox for {{ plat.os_arch_pretty or plat.os_pretty }}"
            data-testid="{{ id }}-{{ plat.os }}"
            {% if plat.os == 'android' %}data-cta-type="firefox_mobile"
            {% elif plat.os == 'ios' %}data-cta-type="firefox_mobile"
diff --git a/bedrock/firefox/templates/firefox/includes/download-list.html b/bedrock/firefox/templates/firefox/includes/download-list.html
index 6d10848520c..322dbb1a605 100644
--- a/bedrock/firefox/templates/firefox/includes/download-list.html
+++ b/bedrock/firefox/templates/firefox/includes/download-list.html
@@ -11,8 +11,8 @@
         <li class="os_{{ plat.os }}{% if plat.arch %} {{ plat.arch }}{% endif %}">
           <a href="{{ plat.download_link_direct or plat.download_link }}"
             class="download-link"
-            data-link-type="download"
             data-download-version="{{ plat.os }}"
+            data-cta-text="Download Firefox for {{ plat.os_arch_pretty or plat.os_pretty }}"
             data-cta-type="firefox">{{ plat.os_arch_pretty or plat.os_pretty }}</a>
         </li>
       {%- endfor %}
diff --git a/bedrock/firefox/templates/firefox/includes/macros.html b/bedrock/firefox/templates/firefox/includes/macros.html
index dca4b871b4a..86b4c530f82 100644
--- a/bedrock/firefox/templates/firefox/includes/macros.html
+++ b/bedrock/firefox/templates/firefox/includes/macros.html
@@ -9,7 +9,14 @@
   {% set os = 'win' if build == '32' else 'win64' %}
   <div class="firefox-platform-button-windows">
     <div class="firefox-platform-button">
-      <a class="download-link {{ class_name }} mzp-t-xl mzp-c-button mzp-t-product ga-product-download" id="{{ id }}" href="{{ settings.BOUNCER_URL }}?product=firefox-stub&os={{ os }}&lang={{ LANG }}" data-link-type="download" data-display-name="Windows {{ build }}-bit" data-download-version="{{ os }}" data-cta-type="firefox" data-cta-position="{{ position }}">
+      <a class="download-link {{ class_name }} mzp-t-xl mzp-c-button mzp-t-product ga-product-download"
+        id="{{ id }}"
+        href="{{ settings.BOUNCER_URL }}?product=firefox-stub&os={{ os }}&lang={{ LANG }}"
+        data-download-version="{{ os }}"
+        data-cta-text="Download Now"
+        data-cta-type="firefox"
+        data-cta-position="{{ position }}"
+        >
         <strong class="download-title">
           {{ cta_copy }}
         </strong>
@@ -33,7 +40,13 @@
 {% macro firefox_download_desktop_button_mac(cta_copy=ftl('download-button-download-now'), id='download-button-desktop-release-osx', position='primary cta') -%}
   <div class="firefox-platform-button-mac">
     <div class="firefox-platform-button">
-      <a class="download-link os_osx mzp-t-xl mzp-c-button mzp-t-product ga-product-download" id="{{ id }}" href="{{ settings.BOUNCER_URL }}?product=firefox-latest-ssl&os=osx&lang={{ LANG }}" data-link-type="download" data-display-name="macOS" data-download-version="osx" data-cta-type="firefox" data-cta-position="{{ position }}">
+      <a class="download-link os_osx mzp-t-xl mzp-c-button mzp-t-product ga-product-download"
+        id="{{ id }}" href="{{ settings.BOUNCER_URL }}?product=firefox-latest-ssl&os=osx&lang={{ LANG }}"
+        data-download-version="osx"
+        data-cta-text="Download Now"
+        data-cta-type="firefox"
+        data-cta-position="{{ position }}"
+        >
         <strong class="download-title">
           {{ cta_copy }}
         </strong>
diff --git a/docs/attribution/0001-analytics.rst b/docs/attribution/0001-analytics.rst
index bf4c8ac0214..6a144bdcff2 100644
--- a/docs/attribution/0001-analytics.rst
+++ b/docs/attribution/0001-analytics.rst
@@ -243,6 +243,78 @@ required.
 +----------------------------+-------------------------------------------------------------------------------------------------------------+
 
 
+GA4
+---
+
+.. Note::
+
+    The migration to GA4 has begun but is incomplete.
+
+    When adding any new elements to a Bedrock page, please follow the below guidelines
+    to ensure accurate analytics tracking.
+
+Generic CTAs
+~~~~~~~~~~~~
+
+For all generic CTA links and ``<button>`` elements, add these data attributes
+(* indicates a required attribute):
+
++-----------------------+---------------------------------------------------------------------------+
+| Data Attribute        | Expected Value (lowercase)                                                |
++=======================+===========================================================================+
+| ``data-cta-type`` *   | Link type (e.g. ``navigation``, ``footer``, or ``button``)                |
++-----------------------+---------------------------------------------------------------------------+
+| ``data-cta-text``     | name or text of the link                                                  |
++-----------------------+---------------------------------------------------------------------------+
+| ``data-cta-position`` | Location of CTA on the page (e.g. ``primary``, ``secondary``, ``header``) |
++-----------------------+---------------------------------------------------------------------------+
+
+For all links to accounts.firefox.com use these data attributes (* indicates a required attribute):
+
++-----------------------+----------------------------------------------------------------------------------+
+| Data Attribute        | Expected Value                                                                   |
++=======================+==================================================================================+
+| ``data-cta-type`` *   | fxa-servicename (e.g. ``fxa-sync``, ``fxa-monitor``)                             |
++-----------------------+----------------------------------------------------------------------------------+
+| ``data-cta-text``     | Name or text of the link (e.g. ``Sign Up``, ``Join Now``, ``Start Here``).       |
+|                       |                                                                                  |
+|                       | We use this when the link text is not useful, as is the case with many           |
+|                       | account forms that say, ``Continue``. We replace ``Continue`` with ``Register``. |
++-----------------------+----------------------------------------------------------------------------------+
+| ``data-cta-position`` | Location of CTA on the page (e.g. ``primary``, ``secondary``, ``header``)        |
++-----------------------+----------------------------------------------------------------------------------+
+
+Links identified with ``data-cta-type`` become UA events with the following format:
+
+| **Category:** ``cta click``
+| **Action:** ``cta: {{data-cta-type}}``
+| **Label:** ``{{data-cta-text}}``
+| **CD Index 9 - CTA Position:** ``{{data-cta-position}}``
+
+
+Download Links
+~~~~~~~~~~~~~~
+
+For Firefox download buttons, add these data attributes (* indicates a required attribute).
+Note that ``data-download-name`` and ``data-download-version`` should be included for download
+buttons that serve multiple platforms. For mobile specific store badges, they are not strictly
+required.
+
++----------------------------+-------------------------------------------------------------------------------------------------------------+
+| Data Attribute             | Expected Value                                                                                              |
++============================+=============================================================================================================+
+| ``data-link-type`` *       | ``download``                                                                                                |
++----------------------------+-------------------------------------------------------------------------------------------------------------+
+| ``data-download-os`` *     | ``Desktop``, ``Android``, ``iOS``                                                                           |
++----------------------------+-------------------------------------------------------------------------------------------------------------+
+| ``data-download-name``     | ``Windows 32-bit``, ``Windows 64-bit``, ``macOS``, ``Linux 32-bit``, ``Linux 64-bit``, ``iOS``, ``Android`` |
++----------------------------+-------------------------------------------------------------------------------------------------------------+
+| ``data-download-version``  | ``win``, ``win64``, ``osx``, ``linux``, ``linux64``, ``ios``, ``android``                                   |
++----------------------------+-------------------------------------------------------------------------------------------------------------+
+| ``data-cta-position`` | ``primary``, ``secondary``, ``nav``, ``other``                                                              |
++----------------------------+-------------------------------------------------------------------------------------------------------------+
+
+
 GA4
 ---