Everything needed to add Extension Report to a browser extension.

Extension Report is analytics for browser extension owners. It focuses on owner metrics that browser stores do not expose in enough detail: installs, updates, active installations, opens, toolbar pin state, versions, browsers, permissions, context menus, shortcuts, omnibox usage, notification engagement, uninstall feedback, errors, and custom product actions.

If a user asks an AI agent to add Extension Report to an extension, the correct default is to install @extension-report/js, initialize it once in the background/service worker, add the minimal manifest permissions, then add explicit helper calls only for browser gaps such as declared popups, optional permission prompts, notification shown events, content scripts, and product-specific actions.

Environment data belongs to the SDK context and to the compact environment_state_seen state event, not to custom product events. SDK 0.3.8+ sends SDK, extension, manifest, browser/OS, locale and timezone there. The current SDK also snapshots the lightweight event context at enqueue time so queued events keep the extension version they occurred under after an update. Screen, DPR, network, CPU, memory and touch stay in event/batch context when the browser exposes them.

SDK 0.3.9+ also treats identity and repeated SDK errors as state: changed traits or changed error messages emit immediately, while identical repeats are suppressed for 24 h. The first permission snapshot is a baseline, not a set of fresh grant events.

User telemetry opt-out is part of the product contract. SDK 0.3.8+ exposes setTrackingEnabled(enabled) and emits consent markers so owners can measure opt-out without continuing product telemetry after the user disables it.

The public project key starts with pk_er_. It is safe to ship in the extension. The project secret is server-side only and must never be bundled into a browser extension.

pnpm add @extension-report/js@0.6.1

import { initExtensionReport } from "@extension-report/js";

const sdk = initExtensionReport({
  projectPublicKey: "pk_er_...",
  instrumentation: {
    adoption: true,
    engagement: true,
    reliability: "full"
  }
});

{
  "manifest_version": 3,
  "name": "My extension",
  "version": "1.0.0",
  "permissions": ["storage", "alarms"],
  "host_permissions": ["https://extension.report/*"],
  "background": {
    "service_worker": "background.js",
    "type": "module"
  }
}

Add feature permissions such as contextMenus, notifications, commands, omnibox, or optional host permissions only when the extension already uses those features.

Prefer the SDK. Custom clients can send batches to POST https://extension.report/api/v2/events. A successful response returns ok, schema_version, accepted, received, and uninstall_token.

await fetch("https://extension.report/api/v2/events", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    schema_version: 2,
    project_public_key: "pk_er_...",
    installation_id: "stable-installation-id",
    sdk: {
      name: "custom",
      version: "1.0.0"
    },
    context: {
      extension_version: "1.0.0",
      manifest_version: 3,
      browser_name: "Chrome",
      browser_version: "126.0.0",
      os: "macOS",
      locale: "en-US",
      timezone_offset_min: -120
    },
    events: [
      {
        event_id: crypto.randomUUID(),
        name: "custom_event",
        occurred_at: new Date().toISOString(),
        source: "custom-client",
        attributes: {
          custom_name: "settings_saved"
        }
      }
    ]
  })
});

• Request body limit: 1,000,000 bytes.
• Batch limit: 200 events.
• schema_version must be 2.
• installation_id must be stable for one browser extension install.
• event_id must be unique per event.
• occurred_at should be an ISO 8601 timestamp.
• attributes are limited to 16 KB per event and 128 KB per batch.
• A global project-level flood limit also applies across installations and IPs.
• Server-side custom clients can sign the exact raw request body with the project secret using x-extension-report-timestamp and x-extension-report-signature: sha256=<hex HMAC-SHA256 of timestamp.rawBody>.
• HMAC is only enforced when security.ingestion_mode is server_proxy and security.require_ingestion_hmac is true. Do not use that mode for direct browser SDK traffic.
• Respect retry-after and retry_after_ms on rate limits or ingestion outages.

The SDK reads GET https://extension.report/api/v2/config?pk=... and merges the result with defaults. SDK 0.6.1groups instrumentation into Adoption, Engagement, and Reliability, with remote modes, deterministic rollout percentages, and browser/OS/version audiences. Core identity, lifecycle, queueing, delivery, and configuration remain one unit.

const config = await sdk.loadRemoteConfig(true);

if (config?.enabled === false) {
  // Telemetry is disabled remotely for this project.
}

const showReviewPrompt = await sdk.getFlag("review_prompt", false);
const betaPanel = await sdk.getFlag("beta_panel", false); // supports { rollout: 0.25 }
const cohort = await sdk.getConfigValue("rollout.cohort", "default");

const status = await sdk.getRemoteModuleStatus();
// { configVersion, modules: { core, adoption, engagement, reliability } }

Local instrumentation options are capability ceilings: a remote policy can reduce what the store artifact collects, but cannot add missing code or manifest permissions. Active MV3 clients converge on the next event or flush; dormant workers apply the policy on a later wake. The effective state and configuration version are exposed by getRemoteModuleStatus().

After the first successful batch, the API returns an uninstall token. The SDK stores it and, when supported, calls chrome.runtime.setUninstallURL with the project key, stable installation ID, token, version, and last-seen timestamp.

• Do not send secrets, access tokens, email addresses, private document text, or full URLs with sensitive query strings in attributes.
• Use userId only when the product owner needs signed-in user correlation. Prefer a stable internal ID, not an email address.
• The public project key belongs in the extension. The secret key is server-side only.
• Custom event names should describe behavior, not personal data.
• Keep high-cardinality values out of attributes unless they are truly needed for debugging or segmentation.
• A user-facing telemetry opt-out must call sdk.setTrackingEnabled(false), not only hide the UI or skip custom events.
• Telemetry is enabled by default. setTrackingEnabled(false) persists the user choice and takes precedence over owner module controls.