---
title: Instrument and configure the Browser Unified SDK
description: "Configure each product in the Amplitude Browser Unified SDK, fetch Feature Experiment variants, control Session Replay and Guides and Surveys, and run more than one instance."
product: analytics
lang: en
last_updated: 2026-10-29
token_estimate: 2229
---
# Instrument and configure the Browser Unified SDK

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

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 [Instrument and configure Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/instrument-and-configure). For signatures, go to the [Browser Unified SDK reference](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/reference). For changes between versions, go to the [`@amplitude/unified` changelog](https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/unified/CHANGELOG.md).

## Configure each product

### How initAll sets up each product

[`initAll()`](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/reference#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:

```ts
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`.

> **Warning:** EU projects lose the data center setting inside analytics
>
> `initAll("KEY", { analytics: { serverZone: "EU" } })` sends events to the US data center. Move `serverZone` to the top level.

### Pass options to each product

Each product block accepts that product's options:

```ts
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,
  },
});
```

| Block | Accepts |
| --- | --- |
| `analytics` | Every [Browser SDK 2 option](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/reference#configuration-options). |
| `sessionReplay` | [Session Replay plugin options](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#configuration), except the shared options. |
| `experiment` | [Experiment JavaScript SDK options](https://amplitude.com/docs/sdks/experiment-sdks/experiment-javascript#configuration), plus `deploymentKey`. |
| `engagement` | [Guides and Surveys options](https://amplitude.com/docs/sdks/guides-and-surveys/sdk#initialize-the-sdk), plus `skip`. |

## 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.

```ts
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](https://amplitude.com/docs/sdks/experiment-sdks/experiment-javascript).

### 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.

```ts
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()`](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/reference#sessionreplay) returns the Session Replay client after `initAll()` resolves:

```ts
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](https://amplitude.com/docs/sdks/session-replay/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`:

```ts
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`:

```ts
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](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/instrument-and-configure#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:

```text
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](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/instrument-and-configure#data-delivery) in Browser SDK 2.