WT-964 Refactor stub attribution by maureenlholland · Pull Request #1296 · mozmeao/springfield

maureenlholland · 2026-04-23T12:47:40Z

One-line summary

Simplify and clarify download attribution data flow

Significant changes and points to review

Refactored attribution approach should be gated behind a switch. When that switch is active, the following changes should be applied:

REMOVED

stub-attribution-consent (now handled through GTM consent mode)

REPLACED

stub-attribution (now download-attribution)
stub-attribution-init (now download-attribution-init)
thanks, thanks-direct, thanks-init (now auto-download)

ADDED

download-attribution
- completely isolates essential and analytics data (with separate triggers)
download-attribution-init (the default that runs on all pages)
- initializes an essential attribution update (the LAST essential information is what we pass to the installer, any previous essential information will be overwritten or removed)
- attaches any existing download-attribution information to download links
auto-download (replaces the default init behaviour on pages where downloads should start automatically)
- if essential information, adds/updates the download attribution cookie before starting download
- if no essential information, starts download immediately

UPDATED

Analytics initialization happens inside consent util for GTM analytics storage
Download as default JS no longer contains consent logic (this is already handled with GTM)
RTAMO uses a new template with a forced essential campaign and auto-download JS
Thanks template used auto-download JS

Rough edges:

data validation mixes rtamo-specific validation with general content length validation

Issue / Bugzilla link

https://mozilla-hub.atlassian.net/browse/WT-964 [moz only]

links to docs on current behaviour and refactor plan on ticket

Follow up work:

chore: remove the override campaign value (fallback and force cover our use cases)
decouple the thanks prefix from auto-download

Testing

Consent gating

Analytics

should not fire when
- consent required geo and no pref allowing analytics
- any geo and DNT
- any geo and GPC
- any geo and pref denying analytics
should fire
- consent required geo and pref allowing analytics
- not consent required geo and no explicit denial signal (DNT/GPC/pref)

Essential

should always fire
- consent required geo and pref allowing analytics
- not consent required geo and no explicit denial signal (DNT/GPC/pref)
- consent required geo and no pref allowing analytics
- any geo and DNT
- any geo and GPC
- any geo and pref denying analytics

No download attribution cookie (create)

Analytics

Add if consent gates pass

Essential

Add if essential forced campaign in HTML
Add if checked checkbox for essential campaign

Existing download attribution cookie (update)

Analytics

add if consent granted
preserve if essential update happens
preserve if new analytics data (first touch, pre-existing wins over new)

Essential

preserve if analytics update happens
add new essential data to replace old (last touch, new wins over pre-existing)

Existing download attribution cookie (remove)

Analytics

remove if consent denied

Essential

remove if user unchecks essential feature checkbox (i.e. download as default)
remove if user leaves essential feature page before clicking download CTA (i.e. smart window)
- this covers the case where essential data is now stale and would provide an unexpected feature flow on download
- auto-download page is an exception, where we can assume any essential data is from the immediately preceding page and is the expected feature flow

Auto-download

should start download immediately with existing download attribution if no new essential data on page
should create/update essential data attribution before download if new essential data is on page (i.e. rtamo)

Regression tests

No user-facing change (unless indicated)

RTAMO auto download (DNT/GPC check no longer needed now we can cleanly remove analytics data according to consent and only apply essential data)

might be easiest to fully test once on dev/stage, instructions here [Moz only]
this has no impact on prod until we start directing RTAMO links to www.firefox.com (currently directing to www.mozilla.org)

Download as default checkbox (should now work for consent required geos, only applying essential data)

toggle checkbox to see essential data added and removed: https://www-demo4.springfield.moz.works/en-US/test-2/

Smart Window

must be US geo: https://www-demo4.springfield.moz.works/en-US/test/

/all after user selections

ensure download attribution is added to download link: https://www-demo4.springfield.moz.works/en-US/download/all/

/thanks auto download

click download link on https://www-demo4.springfield.moz.works/en-US/test-2/
confirm you see any expected download attribution attached to the download link with stub-attribution-code param

/landing/get with marketing opt-out checkbox

confirm opt-in (from banner) and opt-out (from checkbox) work as expected: https://www-demo4.springfield.moz.works/en-US/landing/get/

Fallback campaign

confirm analytics has kit campaign if analytics allowed and no utm_campaign in URL: https://www-demo4.springfield.moz.works/en-US/kit/
navigate to https://www-demo4.springfield.moz.works/en-US/test/ or https://www-demo4.springfield.moz.works/en-US/test-2 and confirm the analytics campaign is overwritten by the essential campaign

codecov · 2026-04-23T17:24:27Z

Codecov Report

❌ Patch coverage is 45.94595% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.85%. Comparing base (e0d69b9) to head (62c6b39).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
springfield/firefox/views.py	45.94%	20 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1296      +/-   ##
==========================================
- Coverage   79.96%   79.85%   -0.12%     
==========================================
  Files         149      149              
  Lines        9655     9688      +33     
==========================================
+ Hits         7721     7736      +15     
- Misses       1934     1952      +18

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…analytics data We always want to include essential data for the download. We conditionally want to include analytics data (based on consent status). We also want to simplify the logic of this flow. The existing stub-attribution JS contains a lot of complex, nested conditionals which has resulted in hard-to-debug issues and makes further development difficult. Refactored attribution approach should be gated behind a switch. When that switch is active, the following changes should be applied: REMOVED - stub-attribution-consent (now handled through GTM consent mode) REPLACED - stub-attribution (now download-attribution) - stub-attribution-init (now download-attribution-init) - thanks, thanks-direct, thanks-init (now auto-download) ADDED - download-attribution - completely isolates essential and analytics data (with separate triggers) - download-attribution-init (the default that runs on all pages) - initializes an essential attribution update (the LAST essential information is what we pass to the installer, any previous essential information will be overwritten or removed) - attaches any existing download-attribution information to download links - auto-download (replaces the default init behaviour on pages where downloads should start automatically) - if essential information, adds/updates the download attribution cookie before starting download - if no essential information, starts download immediately UPDATED - Analytics initialization happens inside consent util for GTM analytics storage - Download as default JS no longer contains consent logic (this is already handled with GTM) - RTAMO uses a new template with a forced essential campaign and auto-download JS - Thanks template used auto-download JS

We can trigger initAnalytics based on GTM consent analytics storage This allows consent logic to live in one place and ensures it is consistently applied for analytics download attribution. The search params JS has moved into the site bundle to ensure it is defined at the time the GTM logic runs. Without this change, analytics initialization would always fail at download attribution functional requirements check. In future, we may create a custom GTM trigger that fires based on the analytics storage consent state.

This is a combination of thanks, thanks-init, and thanks-direct logic Copy-pasted with superficial changes: - shouldAutoDownload - getDownloadURL - beginFirefoxDownload - onSuccess - onTimeout Auto-download pages will not use the default download attribution init logic from the stub attribution block. These pages will only create/update download attribution if there is essential data to pass to the download installer. Otherwise, they will attempt to start download immediately. There is a timeout to prevent an overly long wait before download auto-starts (i.e. if the stub attribution service response is slow). This means we prioritize a timely download over passing essential information.

This applies to all except auto-download pages. On those pages, we can assume the user clicked to download from the preceding page, and the preceding page set all necessary attribution data. This change also removes fallback values in python code because we cannot reliably know if marketing data is allowed at this point.

…ampaign value

We should only apply defaults for analytics values once we confirm there is a ga4 client id value Otherwise, consider essential only and pass nothing but the campaign

To recreate: - Consent required geo goes to /landing/get and accepts analytics from banner - Analytics information is added to download attribution - Consent required geo goes to /privacy/websites/cookie-settings and updates analytics preference to denied - Analytics information should be removed from download attribution This is commented as a temporary workaround because we are still conditionally loading GTM (and GTAG initialization is related to that). This means there are pages where GTAG is not defined but we might still need to remove pre-existing analytics information. Moving the removal action above the GTAG check ensures it always runs when consent is denied.

…l of essential expectations

maureenlholland · 2026-05-13T16:57:33Z

TODO:

address any legit copilot feedback
add tests for adding the attribution params to download links (and updating and removing)
debug missing GA4 on demo

Copilot

Pull request overview

This PR introduces a refactored “download attribution” flow (renaming/replacing parts of the legacy “stub attribution” approach) with a goal of cleanly separating essential attribution data from analytics attribution data, and wiring the new behavior behind a Waffle switch.

Changes:

Added a new DownloadAttribution client module with separate essential vs analytics triggers, plus an init bundle and an auto-download bundle.
Updated templates/bundles to conditionally load new v2 JS bundles (download attribution, auto-download, download-as-default v2, firefox_all v2) when the switch is enabled.
Added Playwright coverage for create/update/remove behaviors of the new attribution cookies and service calls.

Review completed using the repository’s custom Copilot instructions and AGENTS.md guidance.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
`tests/playwright/specs/download-attribution/create.spec.js`	Adds Playwright coverage for creating analytics/essential attribution cookies and consent gating.
`tests/playwright/specs/download-attribution/update.spec.js`	Adds Playwright coverage for “preserve/override” update rules between essential and analytics attribution.
`tests/playwright/specs/download-attribution/remove.spec.js`	Adds Playwright coverage for removing analytics and essential attribution under consent/flow changes.
`springfield/privacy/templates/privacy/cookie-settings-flare26.html`	Adds a test id hook used by Playwright to target the analytics consent UI.
`springfield/firefox/views.py`	Refactors server-side stub attribution signing defaults behind a switch; updates template selection for direct downloads.
`springfield/firefox/templates/firefox/download/rtamo.html`	New RTAMO thanks template that forces an essential campaign via `<html>` attributes.
`springfield/firefox/templates/firefox/download/desktop/thanks.html`	Switches `/thanks` behavior to use `auto-download` JS and suppress attribution init when refactor is enabled.
`springfield/firefox/templates/firefox/download/basic/thanks.html`	Same as above for the basic thanks template.
`springfield/firefox/templates/firefox/all/base.html`	Switches `/all` JS bundle to a v2 initializer when refactor is enabled.
`springfield/cms/templates/cms/thanks_page.html`	Switches CMS thanks pages to `auto-download` and suppresses attribution init when refactor is enabled.
`springfield/cms/templates/cms/base-flare26.html`	Conditionally swaps `stub-attribution` → `download-attribution` and `download_as_default` → `download_as_default-v2`.
`media/static-bundles.json`	Registers new v2 bundles and repositions `search-params` into the base bundle.
`media/js/firefox/download/desktop/download-as-default-v2.es6.js`	New download-as-default integration that updates essential attribution on checkbox changes.
`media/js/firefox/download/desktop/download-as-default-init-v2.es6.js`	Initializes the new download-as-default v2 module.
`media/js/firefox/download/auto-download.es6.js`	New auto-download flow that can force an essential attribution update before starting a download.
`media/js/firefox/all/all-init-v2.es6.js`	New `/all` initializer that re-applies attribution to partially-fetched download links.
`media/js/base/download-attribution/download-attribution.es6.js`	New core implementation for essential+analytics attribution with separate raw cookies and re-signing.
`media/js/base/download-attribution/download-attribution-init.es6.js`	Default init that refreshes essential attribution and applies signed attribution to links.
`media/js/base/consent/utils.es6.js`	Hooks analytics consent changes to attribution analytics init/removal.

+window.dataLayer = window.dataLayer || [];
+
+/**


+    /**
+     * Update essential data based on checkbox state
+     */
+    if (!checked) {
+        window.Mozilla.DownloadAttribution.initEssential(null, () => {
+            DownloadAsDefault.bindEvents();
+        });
+    } else {
+        window.Mozilla.DownloadAttribution.initEssential(
+            DownloadAsDefault.CAMPAIGN,
+            () => {
+                DownloadAsDefault.bindEvents();
+            }


+if (
+    Mozilla.DownloadAttribution !== undefined &&
+    document.documentElement.hasAttribute(
+        'data-stub-attribution-campaign-force'
+    )
+) {
+    // Custom success and timeout callbacks are only relevant for direct attribution
+    // (i.e. when we have updated the cookie on the auto-download page)
+    Mozilla.DownloadAttribution.successCallback = onSuccess;
+    Mozilla.DownloadAttribution.timeoutCallback = onTimeout;
+    // Don't wait too long before starting download
+    // (even if it means we have to leave the essential information out)
+    timeout = setTimeout(onTimeout, 2000);
+    Mozilla.DownloadAttribution.initEssential();
+} else {
+    // Otherwise, we can assume an existing cookie has latest data
+    Mozilla.DownloadAttribution.applyAttributionDataToLinks();
+    beginFirefoxDownload();


+            const existingCookies = await page.context().cookies();
+            const existingEssentialCookie = existingCookies.find(
+                (c) => c.name === 'moz-download-attribution-essential-raw'
+            );
+            const existingAnalyticsCookie = existingCookies.find(
+                (c) => c.name === 'moz-download-attribution-essential-raw'
+            );
+            expect(existingEssentialCookie).toBeDefined();
+            const existingEssentialCookieData = JSON.parse(
+                decodeURIComponent(existingEssentialCookie.value)
+            );
+            const existingAnalyticsCookieData = JSON.parse(
+                decodeURIComponent(existingAnalyticsCookie.value)
+            );


+                const acceptButton = page.getByTestId(
+                    'consent-banner-accept-button'
+                );
+                acceptButton.click();


+                const acceptButton = page.getByTestId(
+                    'consent-banner-accept-button'
+                );
+                acceptButton.click();


+                // change consent status
+                const analyticsCategory = await page.getByTestId(
+                    'cookie-consent-analytics'
+                );
+                const disagreeOption =
+                    await analyticsCategory.getByLabel(/I do not agree/i);
+                await disagreeOption.click();
+                const saveButton = await page.getByRole('button', {
+                    name: /Save changes/i
+                });
+                await saveButton.click();
+
+                // Confirm stub attribution service call uses essential campaign param only
+                expect(capture.params).not.toBeNull();
+
+                expect(capture.params.utm_campaign).toBe(
+                    existingEssentialCookieData.utm_campaign


+                await page.waitForFunction(() => {
+                    return document.cookie
+                        .split(';')
+                        .some((c) =>
+                            c
+                                .trim()
+                                .startsWith(
+                                    'moz-download-attribution-analytics-raw='
+                                )
+                        );
+                });
+
+                // Confirm new essential cookie added
+                const cookies = await page.context().cookies();
+                const essentialCookie = cookies.find(
+                    (c) => c.name === 'moz-download-attribution-essential-raw'
+                );
+                expect(essentialCookie).toBeDefined();
+
+                // Confirm stub attribution service params preserve pre-existing analytics data
+                // (with exception of campaign)
+                expect(capture.params).not.toBeNull();
+
+                expect(capture.params.utm_source).toBe(
+                    existingAnalyticsCookieData.utm_source
+                );


…ttribute

maureenlholland added the WIP Work in progress label Apr 23, 2026

stevejalim reviewed Apr 29, 2026

View reviewed changes

Comment thread media/js/base/download-attribution/download-attribution-init.es6.js Outdated

stevejalim reviewed Apr 29, 2026

View reviewed changes

Comment thread media/js/firefox/download/auto-download.es6.js

maureenlholland force-pushed the WT-964--refactor-stub-attribution branch 2 times, most recently from 8e34134 to 5047f3b Compare April 29, 2026 14:33

maureenlholland commented Apr 29, 2026

View reviewed changes

Comment thread springfield/firefox/views.py Outdated

maureenlholland force-pushed the WT-964--refactor-stub-attribution branch 3 times, most recently from 1e53908 to e945dc7 Compare May 7, 2026 17:13

maureenlholland added 2 commits May 13, 2026 14:18

Copy existing Stub Attribution folder and rename to Download Attribution

ede47dc

Convert JS file to ES6

5a79ad6

maureenlholland force-pushed the WT-964--refactor-stub-attribution branch from e945dc7 to bafc009 Compare May 13, 2026 13:46

maureenlholland added 13 commits May 13, 2026 15:08

Add refactored JS bundle and apply behind switch

2901242

Update download as default to simpler attribution flow

e4ac493

Duplicate all-init JS for use with new Download Attribution JS

8efb354

Update all-init-v2 to use DownloadAttribution

dfb55e6

Add E2E download attribution tests

8630374

Auto-download should apply any existing download attribution to download

fb3e452

Add check for valid essential campaigns and fix download as default c…

1e871de

…ampaign value

Rename marketing to analytics for consistency

00cb6ab

All download attribution values default to (not set)

b7b3b92

We should only apply defaults for analytics values once we confirm there is a ga4 client id value Otherwise, consider essential only and pass nothing but the campaign

maureenlholland force-pushed the WT-964--refactor-stub-attribution branch from bafc009 to b7b3b92 Compare May 13, 2026 14:44

maureenlholland added 3 commits May 13, 2026 15:46

Reorg and update comment for default download attribution init JS

2cdfea0

Restore commented out code (was used for local testing)

f5ba0a8

maureenlholland added 3 commits May 13, 2026 17:28

Fix invalid use of waffle switch

48bb9c9

Add removeDownloadAsDefault setup to playwright tests for more contro…

326f6be

…l of essential expectations

Update thanks prefix comment

62c6b39

janriokrause requested a review from Copilot May 13, 2026 16:57

Copilot started reviewing on behalf of janriokrause May 13, 2026 16:58 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

maureenlholland added 2 commits May 18, 2026 13:21

Fix source key typo

de6963a

Gate JS download attribution call behind check for HTML data switch a…

f886354

…ttribute

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WT-964 Refactor stub attribution#1296

WT-964 Refactor stub attribution#1296
maureenlholland wants to merge 23 commits into
mainfrom
WT-964--refactor-stub-attribution

maureenlholland commented Apr 23, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Apr 23, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maureenlholland commented May 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

maureenlholland commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

One-line summary

Significant changes and points to review

Issue / Bugzilla link

Testing

Consent gating

No download attribution cookie (create)

Existing download attribution cookie (update)

Existing download attribution cookie (remove)

Auto-download

Regression tests

Uh oh!

codecov Bot commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maureenlholland commented May 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

maureenlholland commented Apr 23, 2026 •

edited

Loading

codecov Bot commented Apr 23, 2026 •

edited

Loading