Install in a Firefox extension

The SDK is the same one Chrome uses. What differs is the manifest, the background lifecycle, and one uninstall-tracking behaviour that silently breaks if you follow the Chrome guide here. That is why this is a separate page.

1. Install the package

npm install @analyticstrend/extension

Beta versioning

Published at 0.1.0. The API is settled enough to build on, but this is a closed beta and breaking changes will land in minor versions until 1.0.0. Pin an exact version if that matters to you.

2. Initialise in the background script

// background.js
import { initBackground } from "@analyticstrend/extension";

const analytics = await initBackground({
  writeKey: "wk_your_key_here",
  uninstallTracking: true,
});

analytics.track("extension_started");

Identical to Chrome, and that is deliberate. The SDK resolves Firefox's browser namespace or Chromium's chrome namespace itself, so you do not need a polyfill and you do not write two code paths.

3. Declare the manifest

Firefox supports Manifest V3, but background pages are event pages rather than service workers, and Firefox requires an explicit add-on id for several APIs:

{
  "manifest_version": 3,
  "background": { "scripts": ["background.js"], "type": "module" },
  "host_permissions": ["https://analyticstrend.com/*"],
  "browser_specific_settings": {
    "gecko": { "id": "your-extension@example.com", "strict_min_version": "115.0" }
  }
}

Note background.scripts, not background.service_worker. A manifest carrying only the Chrome form will load in Firefox and never run your background code, which presents as "no events at all" with nothing in the console to explain it.

The uninstall-tracking difference

This is the one that bites.

Chrome remembers an uninstall URL across service-worker restarts. Firefox does not. Its event page must call setUninstallURL again on every run of the background script, or uninstall tracking stops working the first time the page unloads, which is within about a minute of install.

Passing uninstallTracking: true to initBackground handles it, because initBackground runs on every background start on both browsers. If you instead call enableUninstallTracking yourself, call it unconditionally at the top level:

// Correct on both browsers.
enableUninstallTracking({ writeKey, anonymousId, endpoint });

// Works on Chrome forever. Stops working on Firefox within the minute.
browser.runtime.onInstalled.addListener(() => {
  enableUninstallTracking({ writeKey, anonymousId, endpoint });
});

onInstalled fires once. On Chrome the URL it set persists, so the bug never shows itself. On Firefox the event page unloads, the URL is forgotten, and uninstalls quietly stop being recorded — with a dashboard that looks fine, just wrong.

Before you submit to AMO

Mozilla reviews add-ons by hand, and the reviewer reads your source. The store policy page covers what they look for and what to write in your data-collection disclosure.

Verify it

Load the add-on temporarily from about:debugging, use it, then check the Events screen in your dashboard. Then remove it and confirm an uninstall event arrives, since that is the path this page exists to protect.