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.2.1. That version bundles Browser SDK 2.49.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
Unified SDK exports
| Export | Signature | Guide |
|---|---|---|
initAll | initAll(apiKey: string, unifiedOptions?: UnifiedOptions): Promise<void> | Initialize the SDK |
experiment | experiment(): IExperimentClient | undefined | Fetch flags and read a variant |
sessionReplay | sessionReplay(): AmplitudeSessionReplay | undefined | Control recording from code |
createInstance | createInstance(): UnifiedClient | Run more than one instance |
createNetworkRequestEvent | createNetworkRequestEvent(properties: NetworkRequestEventProperties): BaseEvent | undefined | createNetworkRequestEvent |
Browser SDK 2 exports
The Unified SDK re-exports these from Browser SDK 2. They behave as the Browser SDK 2 reference describes.
| Export | Signature | Guide |
|---|---|---|
track | track(eventInput: string | BaseEvent, eventProperties?: Record<string, any>, eventOptions?: EventOptions): AmplitudeReturn<Result> | Track events |
identify | identify(identify: Identify, eventOptions?: EventOptions): AmplitudeReturn<Result> | Set user properties |
Identify | new Identify(), with chainable set(), setOnce(), add(), append(), prepend(), preInsert(), postInsert(), remove(), unset(), and clearAll() | Set user properties |
setUserId | setUserId(userId: string | undefined): void | Set the user ID |
logEvent, groupIdentify, setGroup, revenue, flush, add, remove, setTransport, getUserId, getDeviceId, setDeviceId, getIdentity, setIdentity, getSessionId, setSessionId, extendSession, reset, getOptOut, setOptOut | Go to the Browser SDK 2 reference. | Instrument and configure Browser SDK 2 |
Revenue, Types | Go to Revenue and Types. | Track revenue |
Type-only exports
UnifiedOptions, UnifiedSharedOptions, UnifiedClient, and NetworkRequestEventProperties are TypeScript types with no runtime value. Go to UnifiedOptions, UnifiedClient, and createNetworkRequestEvent.
The top-level module doesn't export init() or Browser SDK 2's trackVideo(). Call initAll() instead of init().
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>
| Parameter | Type | Description |
|---|---|---|
apiKey | string | Your Amplitude project API key. |
unifiedOptions | UnifiedOptions | Optional. Go to UnifiedOptions. |
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("AMPLITUDE_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
| Method | Description |
|---|---|
start(): AmplitudeReturn<void> | Starts or resumes recording. Recording still respects sample rate, targeting, opt-out, and remote capture settings. |
stop(): void | Pauses recording without tearing down the SDK. Call start() to resume. |
shutdown(): void | Stops recording and removes event listeners. |
flush(useRetry: boolean): Promise<void> | Uploads recorded data now. Pass true to retry failed uploads. |
getSessionReplayProperties(): { [key: string]: boolean | string | null } | Returns { "[Amplitude] Session Replay ID": "..." } while Session Replay records the session, and {} otherwise. |
getSessionId(): string | number | undefined | Returns the session ID that Session Replay records against. |
setSessionId(sessionId: string | number, deviceId?: string): AmplitudeReturn<void> | Sets the session ID that Session Replay records against. |
init, evaluateTargetingAndCapture | The plugin calls these during setup. Don't call them directly. |
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.
createNetworkRequestEvent
Builds an [Amplitude] Network Request event for a request that your code reports, such as one made outside fetch and XMLHttpRequest. It doesn't send the event. Pass the result to track(). Requires @amplitude/unified 1.2.0 or later.
createNetworkRequestEvent(properties: NetworkRequestEventProperties): BaseEvent | undefined
| Property | Type | Description |
|---|---|---|
url | string | Required. The request URL. The query string and fragment become separate event properties. |
method | string | Required. The HTTP method. |
startTime | number | Required. The request start time, in Unix milliseconds. |
duration | number | Required. The request duration, in milliseconds. |
statusCode | number | Optional. The HTTP status. Defaults to 0. |
requestType | "xhr", "fetch", or "custom" | Optional. Defaults to "custom". |
error | { code?: number; message: string } | Optional. A transport error. |
requestBodySize, responseBodySize | number | Optional. Body sizes, in bytes. |
requestHeaders, responseHeaders | Record<string, string> | Optional. Headers to report. |
requestBody, responseBody | string | Optional. Serialized bodies to report. |
The function returns undefined and logs an error when url or method is empty, or when startTime or duration is negative or not a finite number. It doesn't apply network tracking's filtering or masking rules, so remove sensitive values from the URL, headers, and bodies before you pass them.
const event = amplitude.createNetworkRequestEvent({
url: "https://api.example.com/orders?id=42",
method: "POST",
startTime: Date.now() - 120,
duration: 120,
statusCode: 201,
});
if (event) amplitude.track(event);
UnifiedClient
The interface that the default instance implements and createInstance() returns. It extends the Browser SDK 2 BrowserClient with these members:
| Member | Description |
|---|---|
initAll | Refer to initAll. |
experiment | Refer to experiment. |
sessionReplay | Refer to sessionReplay. |
init | Initializes Analytics only, as Browser SDK 2 init() does. Available on instances from createInstance(), not as a top-level export. |
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.
| Option | Type | Default | Description |
|---|---|---|---|
serverZone | "US" or "EU" | "US" | The data center for every product. Set it here, not in analytics. |
instanceName | string | "$default_instance" | The instance name for every product. Use a distinct name for each instance from createInstance(). |
Product options
| Option | Type | Default | Description |
|---|---|---|---|
analytics | BrowserOptions | {} | Browser SDK 2 options. Go to Configuration options. |
sessionReplay | SessionReplayOptions, without the shared options | {} | Session Replay plugin options. sampleRate defaults to 0, which records nothing. For privacyConfig, go to Mask sensitive content. For the rest, go to Session Replay plugin. |
experiment | ExperimentPluginConfig, without the shared options | {} | Experiment JavaScript SDK options, plus deploymentKey. Go to experiment options. |
engagement | Guides and Surveys InitOptions, without the shared options | {} | Guides and Surveys options, plus skip. Go to engagement options. |
experiment options
| Option | Type | Default | Description |
|---|---|---|---|
deploymentKey | string | The project API key | The Experiment client deployment key. |
| Other options | Varies | Varies | Every Experiment JavaScript SDK option. Version 1.2.1 includes @amplitude/plugin-experiment-browser 1.0.0-beta.52, a beta release. |
engagement options
| Option | Type | Default | Description |
|---|---|---|---|
skip | boolean | false | When true, Guides and Surveys downloads nothing, makes no requests, and writes nothing to storage. Requires @amplitude/unified 1.1.11 or later. |
| Other options | Varies | Varies | Every Guides and Surveys option. |
Was this helpful?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.