Browser Unified SDK reference

This reference documents every public export of @amplitude/unified and every option you can pass to initAll(), verified against version 1.1.43. That version bundles Browser SDK 2.48.1 (@amplitude/analytics-browser), so every analytics method behaves as the Browser SDK 2 reference describes. For changes between versions, go to the @amplitude/unified changelog.

import * as amplitude from "@amplitude/unified";

The top-level functions act on a default instance. Each instance from createInstance() has the same methods, plus init().

Exports

The top-level module doesn't export init(). Call initAll() instead.

Setup

initAll

Initializes Analytics, then adds Session Replay, Feature Experiment, and Guides and Surveys. Call it once per instance on each page load.

initAll(apiKey: string, unifiedOptions?: UnifiedOptions): Promise<void>

initAll() returns a plain Promise, not an AmplitudeReturn, so await it directly. It resolves after every product finishes setup. Calls made before it resolves wait in a queue and run in order afterward.

An initAll() call made while an earlier call is still pending returns the same promise. An initAll() call made after the earlier call resolves runs the full setup again. The repeat call initializes Analytics again, tracks another page view if page view tracking is on, and restarts Session Replay. It also logs Plugin with name @amplitude/unified-library-plugin already exists, skipping registration.

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

experiment

Returns the Feature Experiment client, or undefined before initAll() adds it.

experiment(): IExperimentClient | undefined

The client is the Experiment JavaScript SDK client. The client doesn't fetch flags during initAll(). Call fetch() before variant().

const experiment = amplitude.experiment();
await experiment?.fetch();
const variant = experiment?.variant("checkout-redesign");

sessionReplay

Returns the Session Replay client, or undefined before initAll() adds it.

sessionReplay(): AmplitudeSessionReplay | undefined

const replay = amplitude.sessionReplay();
replay?.stop();

For recording options, go to Session Replay plugin.

createInstance

Creates an independent instance with its own Analytics configuration, identity, queue, and plugins.

createInstance(): UnifiedClient

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

Guides and Surveys initializes once per page. Instances that call initAll() after the first instance ignore their engagement options.

UnifiedClient

The interface that the default instance implements and createInstance() returns. It extends the Browser SDK 2 BrowserClient with these members:

UnifiedOptions

The options object you pass to initAll(). All options are optional.

Shared options

initAll() passes these options to every product and merges them over the same-named option in each product block. An unset shared option still overwrites the same-named product option with undefined.

Product options

experiment options

engagement options