JavaScript (Browser Extension)

Overview

Building for browser extensions (Manifest V3) requires strict adherence to privacy policies and ephemeral lifecycles.

To prevent Chrome Web Store rejections and ensure zero data loss when service workers go to sleep, the AddonPulse Extension SDK is split into two distinct modules:

The Background SDK (/background): Runs in your Service Worker. It handles offline queuing (via IndexedDB), identity persistence, and all network requests.
The Client SDK (/client): Runs in your Popups, Options pages, and Content Scripts. It gathers safe telemetry and passes it to the background script.

Installation

npm install @addonpulse/extension

yarn add @addonpulse/extension

Do not import the root package. You must import specifically from /background or /client depending on where the code is running. Mixing DOM code into your background script will crash the extension.

1. Background Initialization (The Hub)

You must initialize the Background SDK in your extension's Service Worker (background.js or background.ts). This sets up the message listeners and the offline storage queue.

tracker.initialize() must be called synchronously at the top level of your background file. If you wrap it inside an async function or a chrome.runtime.onInstalled hook, Chrome will fail to wake up your Service Worker to process tracking events.

Syntax

import { AddonPulseBackground } from "@addonpulse/extension/background";

const tracker = new AddonPulseBackground(config: AddonPulseConfig);
tracker.initialize();

Example

import { AddonPulseBackground } from "@addonpulse/extension/background";

const tracker = new AddonPulseBackground({
  siteId: "your-site-id",
  debug: process.env.NODE_ENV !== "production"
});

// Must be called synchronously at the top level
tracker.initialize();

Configuration Options

Option	Type	Default	Description
`siteId`	`string`	-	Required. The Site ID for your extension obtained from your AddonPulse instance.
`analyticsHost`	`string`	`https://api.addonpulse.com`	Optional. Override the default API URL (useful for self-hosting).
`debug`	`boolean`	`false`	When `true`, events are logged to the console and not sent to the network. Use this for local development to avoid polluting production data.

2. Client Tracking (The Spool)

Use the Client SDK inside your Extension UI (Popups, Options, Side Panels) or injected Content Scripts. It automatically detects its environment and safely forwards data to your background script.

Tracking Custom Events

Use custom events to track specific user interactions within your extension.

Syntax

import { AddonPulseClient } from "@addonpulse/extension/client";

AddonPulseClient.track(name: string, properties?: Record<string, unknown>);

Example

import { AddonPulseClient } from "@addonpulse/extension/client";

// Track a feature toggle in your popup
document.getElementById("dark-mode-toggle").addEventListener("change", (e) => {
  AddonPulseClient.track("feature_toggled", {
    feature: "dark_mode",
    enabled: e.target.checked
  });
});

Tracking Pageviews

Track when a user opens a specific view in your extension (e.g., opening the popup or options page).

Syntax

AddonPulseClient.pageview();

Privacy First: To prevent Chrome Web Store rejections, the SDK never transmits full URLs or pathnames. It automatically strips the payload down to just the context (e.g., popup, content_script) and the hostname (if injected into a web page).

User Identification

You can associate tracking events with a logged-in user. Because Content Scripts and Popups have isolated storage, you call identify from the client, and the SDK automatically syncs it to the Background script's persistent IndexedDB.

`identify`

Links the extension's anonymous device ID to your application's user ID.

AddonPulseClient.identify(userId: string, traits?: Record<string, unknown>);

Example:

// Call this after a successful login in your extension
async function handleLogin(credentials) {
  const user = await myAuthApi.login(credentials);

  AddonPulseClient.identify(user.id, {
    plan: user.plan,
    email: user.email
  });

  AddonPulseClient.track("user_logged_in");
}

`clearUserId`

Detaches the user ID. Future events will revert to being tracked purely under the anonymous device ID.

AddonPulseClient.clearUserId();

Example:

// Call this when the user logs out
AddonPulseClient.clearUserId();

Skip Patterns (Filtering)

Extensions can be noisy. Skip patterns act as a client-side kill switch to prevent tracking on sensitive domains or muting high-volume background events, saving you infrastructure costs and ensuring compliance.

Skip patterns are managed remotely in your AddonPulse dashboard under Extension Skip Patterns. The Background SDK fetches and caches these rules for 24 hours.

How it matches

Because the Extension SDK strips full URLs for privacy, patterns are matched against two fields:

hostname: The domain the content script is running on (e.g., chase.com).
event_name: The name of the custom event (e.g., background_ping).

Wildcards

*: Matches any sequence of characters.

Examples:

*.chase.com: Drops any content-script tracking that occurs on Chase Bank domains.
localhost: Drops tracking when developers are testing the extension locally.
background_*: Drops any custom events that start with background_.

JavaScript (Browser Extension)

On this page