Browser Unified SDK usage guide

This guide covers the tasks specific to the Browser Unified SDK (@amplitude/unified): configuring products, using Feature Experiment and Session Replay, and turning off Guides and Surveys. Tracking events, identifying users, autocapture, and upload behavior come from the bundled Browser SDK 2 and work the same way. For those tasks, go to the Browser SDK 2 usage guide. For signatures, go to the Browser Unified SDK reference. For changes between versions, go to the @amplitude/unified changelog.

Configure each product

How initAll sets up each product

initAll() runs these steps in order, and resolves after the last one:

1. Initializes Analytics (Browser SDK 2) with the analytics options.
2. Adds the Session Replay plugin with the sessionReplay options.
3. Adds the Feature Experiment plugin with the experiment options.
4. Adds the Guides and Surveys plugin with the engagement options.

At every step, initAll() merges the shared options, serverZone and instanceName, over the product's own options. The shared value always wins, even when you don't set it: an unset top-level serverZone replaces analytics.serverZone with undefined, and the product falls back to its default, US.

Set shared options at the top level

Set serverZone and instanceName at the top level of the options object, never inside a product block:

amplitude.initAll("YOUR_API_KEY", {
  serverZone: "EU",
  instanceName: "storefront",
});

With serverZone: "EU" at the top level, every product uses the EU data center. Analytics uploads to api.eu.amplitude.com, Session Replay reads its configuration from sr-client-cfg.eu.amplitude.com, and Feature Experiment fetches from api.lab.eu.amplitude.com.

Pass options to each product

Each product block accepts that product's options:

amplitude.initAll("YOUR_API_KEY", {
  serverZone: "EU",
  analytics: {
    autocapture: { elementInteractions: true },
    identityStorage: "localStorage",
  },
  sessionReplay: {
    sampleRate: 0.1,
  },
  experiment: {
    deploymentKey: "YOUR_CLIENT_DEPLOYMENT_KEY",
  },
  engagement: {
    skip: true,
  },
});

Use Feature Experiment

Fetch flags and read a variant

The Feature Experiment client doesn't fetch flags during initAll(). Call fetch() and wait for it before you read a variant. Before the first fetch completes, variant() returns an empty object.

await amplitude.initAll("YOUR_API_KEY", {
  experiment: { deploymentKey: "YOUR_CLIENT_DEPLOYMENT_KEY" },
});

const experiment = amplitude.experiment();
await experiment?.fetch();

const variant = experiment?.variant("checkout-redesign");
if (variant?.value === "treatment") {
  // Show the new checkout.
}

fetch() sends the user ID and device ID from Analytics, so call setUserId() before fetch() when you know the user. For the client's other methods, such as exposure(), all(), and clear(), go to the Experiment JavaScript SDK.

Set the deployment key

Set experiment.deploymentKey to a client deployment key from Amplitude Experiment. If you omit it, the plugin uses your project API key as the deployment key.

The Unified SDK 1.1.43 includes the Experiment plugin as @amplitude/plugin-experiment-browser 1.0.0-beta.51, a beta release.

Use Session Replay

Choose a sample rate

Session Replay records nothing by default, because sessionReplay.sampleRate defaults to 0. Set a value between 0 and 1: 1 records every session, and 0.1 records about one session in ten. Use 1 while you test, then lower it before production.

amplitude.initAll("YOUR_API_KEY", {
  sessionReplay: { sampleRate: 0.1 },
});

Remote configuration in Amplitude can also turn capture off for the project. When capture is off, the log shows Session ... not being captured due to capture being disabled for project or because the remote config could not be fetched.

Control recording from code

amplitude.sessionReplay() returns the Session Replay client after initAll() resolves:

await amplitude.initAll("YOUR_API_KEY", { sessionReplay: { sampleRate: 1 } });

const replay = amplitude.sessionReplay();
replay?.stop(); // Pause recording, for example on a page with sensitive data.
await replay?.flush(false); // Upload recorded data now, without retries.
replay?.start(); // Resume recording.

start() still respects the sample rate, targeting, and opt-out. To stop recording for the rest of the page and remove the Session Replay listeners, call shutdown().

For masking, privacy, and the plugin's other options, go to Session Replay plugin.

Turn off Guides and Surveys

Guides and Surveys initializes by default. During initAll(), it downloads its bundle from cdn.amplitude.com and calls gs.amplitude.com. If you don't use Guides and Surveys, pass skip: true:

amplitude.initAll("YOUR_API_KEY", {
  engagement: { skip: true },
});

With skip: true, Guides and Surveys downloads nothing, makes no requests, and writes no amplitude.engagement.* keys to localStorage. The console logs Engagement SDK init skipped via `skip: true`. The SDK bundle will not be loaded. The skip option requires Unified SDK 1.1.11 or later.

To turn Guides and Surveys on, remove skip: true from your initAll() call and deploy. Don't call initAll() a second time on the same page to turn it on. A second call initializes Analytics again, reinstalls every plugin, tracks another page view, and restarts Session Replay.

Run more than one instance

To send data to a second project, create an instance with createInstance() and give it a distinct instanceName:

await amplitude.initAll("PRODUCTION_API_KEY");

const marketing = amplitude.createInstance();
await marketing.initAll("MARKETING_API_KEY", {
  instanceName: "marketing",
});

amplitude.track("Signup Completed");
marketing.track("Signup Completed");

Each instance initializes its own Analytics, Session Replay, and Feature Experiment. Guides and Surveys initializes once per page, for the first instance that runs initAll(). Later instances ignore their engagement options and log Engagement SDK has already been initialized. Ignoring additional init call. Put your Guides and Surveys options on the instance that initializes first. For how instances keep identity apart, go to Send events to more than one project in Browser SDK 2.

Data delivery

Allow Amplitude in a Content Security Policy

If your site sends a Content-Security-Policy header, allow Amplitude's domains:

script-src  https://*.amplitude.com;
connect-src https://*.amplitude.com;

Unlike Browser SDK 2 installed from npm, the Unified SDK needs script-src even when you bundle it, because Guides and Surveys downloads its bundle from cdn.amplitude.com. If you set engagement: { skip: true }, you need only connect-src.

For uploads, batching, proxies, and offline behavior, go to Data delivery in Browser SDK 2.