UTM Attribution (Algolia domains)

This NPM package aims to unify our capture and storage strategy towards UTMs (Urchin Tracking Module) on all Algolia domains/sub-domains (Website, Blog, Dashboard, Docs, etc.).

Cookie consent

algolia_website_utm_params is categorized in OneTrust as a Targeting cookie (C0004). The package writes it only after the visitor has consented to that category.

• It reads the landing URL and referrer on load — no storage, so no consent required.
• It writes the cookie when OnetrustActiveGroups contains C0004, either already on load or later via the OneTrustGroupsUpdated event.
• It fails closed: without OneTrust on the page, the cookie is never set.

No configuration needed on consumers that import/require the package — the gate ships inside it.

If you load the browser build with a <script> tag, also apply OneTrust's JavaScript Type Re-Writing so the file isn't even fetched before consent:

<script
  type="text/plain"
  class="optanon-category-C0004"
  src="https://cdn.jsdelivr.net/npm/@algolia/utm-attribution/dist/browser/index.min.js"
></script>

Keep the tag in the server-rendered HTML. A tag injected after OneTrust has initialized (document.createElement, next/script with afterInteractive) misses its re-writing pass and never runs.

How to contribute

1. Clone this repository:

git clone [email protected]:algolia/utm-attribution.git

2. Create a branch, update the code, and make a commit and a PR to develop following SEMVER versioning convention.

Releases

Once you consider that the develop branch holds enough changes to release a new version, here are the 5 steps to follow:

1. make sure you're releasing the correct version:

   • Breaking change, bump the first number (1.2.3 -> 2.0.0) - Major
   • New feature, bump the second number (1.2.3 -> 1.3.0) - Minor
   • Bug fixing, bump the third number (1.2.3 -> 1.2.4) - Patch
   • Unsure? Check SEMVER

2. run npm version [your_version]. This will automatically:

   • checkout develop
   • create a branch named with the version number
   • update the version number
   • push it to GitHub

3. have a look at the auto-generated CHANGELOG.md. Update some information manually if needed, commit and push it

4. create two PRs:

   • one to merge [your_version] into develop (this will update the package.json version)
   • the other one to merge [your_version] into main.

5. run npm run publish or yarn publish to push the new release to npm.