UTM install time injection & GTM Data Layer push

[amit-fytq]

Fixes #16178

Remove utm_ query parameters from internal AMO links while browsing to stop pollution of GA4 data*

• Clean URL during browsing
• Remember where the click came from - Store the reference in redux
• Inject UTM at install time only - you click "Add to Firefox", right before Firefox's install API is called, we silently update the URL using history.replaceState(). Firefox reads this and records the attribution.
• Clean up after install — Once the install completes (or fails/cancels), we silently remove the UTM params from the URL again.
• External UTM params are untouched — If someone arrives from an external link like ?utm_source=blog.example.com, we never overwrite those. Firefox reads them directly.

Push page variables to GTM datalayer

On Addon Detail page, push the following variables to GTM datalayer for analytics reporting and dashboard

• Addon Type
• Page Locale

[codecov]

Codecov Report

❌ Patch coverage is 97.40260% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.12%. Comparing base (c1f13a3) to head (0c0de9f).
⚠️ Report is 68 commits behind head on master.

Files with missing lines	Patch %	Lines
src/amo/utils/installAttribution.js	90.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #14130      +/-   ##
==========================================
- Coverage   98.13%   98.12%   -0.01%     
==========================================
  Files         265      267       +2     
  Lines       10648    10714      +66     
  Branches     3285     3304      +19     
==========================================
+ Hits        10449    10513      +64     
- Misses        186      188       +2     
  Partials       13       13              

☔ 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.

[diox]

In #14089 you said:

We are also investigating ways to filter out the data within Google Analytics itself. If we can do that then we won't make any code changes for this. Will update thread later today.

And then you closed the PR. Could you elaborate on why this is necessary ?

[amit-fytq]

In #14089 you said:

We are also investigating ways to filter out the data within Google Analytics itself. If we can do that then we won't make any code changes for this. Will update thread later today.

And then you closed the PR. Could you elaborate on why this is necessary ?

We discussed options with our GA team and they said GA4/GTM filtering is unreliable and can cause other issues with analytics reporting. Their recommendation was to make the change at the app level so that the incorrect data never hits Google Analytics.

[diox]

I'm not done testing this yet, but I noticed something: GA's dataLayer "sees" and records the replaceState() calls you're doing at install as gtm.historyChange event, just like it would for regular client-side navigation events.

Is that going to be an issue in the reporting in GA?

[diox]

This appears to be working at least for the primary hero, but as I commented I'm not sure what the impact of replaceState dance will be in GA...

Regardless, it needs quite a few tests around the primary hero/secondary hero changes + the new install attribution stuff: You have modified tests to ensure URLs are now "clean" but I don't see tests ensuring we are keeping track of the attribution in the redux store, or tests around installation and history manipulation to inject and remove the attribution params.

[diox]

FWIW, inspecting dataLayer after installing from various sources:

• Primary hero ✅ (I can see the replaceState calls being made)
• Secondary hero ❓ (hard to test manually)
• "External" links ✅ (nothing should have changed here)
• Other home shelves ❌ (no attribution recorded)
• Search results ❌ (no attribution recorded)

I haven't tested yet if that actually translates to correct attribution in Firefox itself when it works.

[amit-fytq]

Added the following test coverage

Reducer (test_addoninstallSource.js)

• Confirm initial state is null
• Verify dispatching setAddonInstallSource updates the store with the correct source string
• Verify dispatching clearAddonInstallSource resets the state to null when navigating away
• Verify state is unaffected by unrelated actions

Core logic - injection and cleanup (test_installAttribution.js)

• Verify that calling injectUTMParams(installSource) correctly appends utm_source=addons.mozilla.org, utm_medium=referral, and utm_content=[installSource] to the URL query string.
• Verify that if a user landed on the page with existing external tracking parameters (e.g. from an email campaign or external site), the logic returns early without overwriting the original attribution.
• Verify that removeUTMParams() strips away only the injected parameters (matching DEFAULT_UTM_SOURCE), returning the browser URL to its original, pristine path.
• Verify that removeUTMParams() will never touch or remove external UTM query parameters.

Install lifecycle (TestInstallButtonWrapper.js)

• Verify that if installSource is present in the Redux store, the wrapper executes _injectUTMParams with the stored source exactly when the user clicks "Add to Firefox".
• Verify that _removeUTMParams is always invoked upon completion of the installation.
• Verify that if the user triggers an installation directly without clicking an internal link (so installSource is null), the injection helper is skipped, but the cleanup is still safely run to guarantee idempotence.

[amit-fytq]

Also discussed the other concerns with GA team. They advised that gtm.historyChange event will not impact the reporting or dashboard views

[amit-fytq]

@diox - The test coverage has been expanded and is back to repo baseline

[diox]

@amit-fytq I'm still having the issues I mentioned above. could you add functional tests ensuring install attribution is done correctly when clicking the primary hero, secondary hero, other shelves and search results ?

[amit-fytq]

@amit-fytq I'm still having the issues I mentioned above. could you add functional tests ensuring install attribution is done correctly when clicking the primary hero, secondary hero, other shelves and search results ?

@diox - I am not sure what you mean by "install attribution" in the context of this UTM params removal PR? Do you mean Firefox telemetry attribution?

[diox]

No, I mean the injection of the attribution source at install time

[amit-fytq]

No, I mean the injection of the attribution source at install time

That is covered by the new tests which were added in the latest commit

#14130 (comment)

[diox]

Those test cover individual component behavior. I'm interested in having functional tests that start from displaying the primary/secondary hero or shelves on the homepage, or search results, and end up with an install. There is no coverage for that currently (onInternalLinkClick() in SecondaryHero is not covered, neither is the dispatch(setAddonInstallSource(addonInstallSource)) call in SearchResult).

As I said above I could only get the end to end attribution to work properly with the primary hero, so something looks broken somewhere - having tests for that flow would help prove that it's working properly in all those cases.

[amit-fytq]

@diox It seems the SearchResult component is invoking e.stopPropagation() inside its onClickAddon handler. This is preventing the click event from bubbling up to the wrapper <li>, which houses the onClickResult handler which dispatches setAddonInstallSource to Redux.

I'll fix this

[amit-fytq]

@diox please review