Get started with the Browser Unified SDK

For web developers10 minBeginner

This guide helps you install the Browser Unified SDK (@amplitude/unified), initialize every product it includes with one call, and send one custom event to Amplitude. For the full option list, go to UnifiedOptions. For changes between versions, go to the @amplitude/unified changelog.

The Unified SDK bundles Browser SDK 2 (@amplitude/analytics-browser) with Session Replay, Feature Experiment, and Guides and Surveys. Every analytics method and option works the same as in Browser SDK 2. If you need Analytics only, install Browser SDK 2 instead. Don't install both packages on the same page. To compare npm, the Unified Script, and Google Tag Manager, go to Choose a browser installation.

Prerequisites

An Amplitude project and its API key. To find the key, go to Settings > Projects, select your project, and open General.
The data center your organization uses: US (default) or EU.
A JavaScript bundler, such as webpack, Vite, or esbuild. The Unified SDK installs from npm only. For a script tag, use the Unified Script.
A page served over http:// or https://. Pages opened from file:// can't set cookies, so the SDK can't persist identity between loads.

Install the SDK

bash

npm install @amplitude/unified

Then import the package:

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

Fix installation problems

Symptom	Cause	Fix
`amplitude.init is not a function`	The Unified package doesn't export `init()`.	Call `initAll()` instead.
Two Amplitude instances, or events sent twice	The page also loads `@amplitude/analytics-browser`, the script loader, or the Unified Script.	Keep one Amplitude entry point per page.
Bundle size grew more than expected	The package includes every product and loads the Guides and Surveys bundle from the CDN at runtime.	Install Browser SDK 2 and add only the products you need. Go to Choose a browser installation.

Initialize the SDK

Call initAll() once, as early as possible. It initializes Analytics first, then adds Session Replay, Feature Experiment, and Guides and Surveys as plugins. The SDK queues any calls you make before initAll() finishes and runs them afterward.

amplitude.initAll("YOUR_API_KEY", {
  serverZone: "EU", // Omit for US projects.
  analytics: { autocapture: true },
  sessionReplay: { sampleRate: 1 }, // Records every session. Lower this before production.
});

Set serverZone at the top level, not inside analytics. initAll() passes the top-level value to every product and overwrites the per-product value, even when you leave the top-level value unset.

Session Replay records nothing until you set sessionReplay.sampleRate above 0.

initAll() doesn't accept a user ID argument. Call amplitude.setUserId() after it.

Fix initialization problems

Symptom	Cause	Fix
EU project, but events reach the US data center or fail with `Invalid API key`	`serverZone: "EU"` is inside `analytics`. The unset top-level `serverZone` overwrites it.	Move `serverZone` to the top level of the `initAll()` options.
Console warning: `Plugin with name @amplitude/unified-library-plugin already exists, skipping registration`	`initAll()` ran a second time on the same instance. The second call initializes Analytics again and restarts every plugin.	Call `initAll()` once per page load.
Log: `Session ... not being captured due to capture being disabled for project or because the remote config could not be fetched.`	Session Replay capture is off for the project, or the API key is wrong.	Check the API key and `serverZone`, and confirm that the project has Session Replay turned on.
No replays, and no capture log	`sessionReplay.sampleRate` is `0`, the default.	Set `sampleRate` above `0`.
Clicks or inputs stop working after `initAll()` in an Angular app	`initAll()` calls Browser SDK 2's `init()`, and Zone.js wraps DOM APIs that autocapture also patches.	Call `initAll()` in `main.ts` before `bootstrapApplication`, or inside `NgZone.runOutsideAngular()`.
Errors during server-side rendering	`initAll()` runs on the server (Next.js, Nuxt, SvelteKit, Remix).	Call `initAll()` only in browser code. Go to the Next.js installation guide.

For analytics initialization problems, such as cookies or autocapture warnings, go to Fix initialization problems in Browser SDK 2.

Send a first event

Track one custom event and wait for the upload result. track() returns an object whose promise resolves after the upload attempt.

const result = await amplitude.track("Sign Up Clicked", {
  plan: "starter",
}).promise;

console.log(result.code, result.message);
// 200 "Event tracked successfully"

Fix upload problems

The Unified SDK uploads events through the bundled Browser SDK 2, so the result codes match Browser SDK 2. For every result.code and result.message, go to Fix upload problems in Browser SDK 2.

Confirm the event in Amplitude

In Amplitude, open User Lookup and search for the device ID from amplitude.getDeviceId().
Open the Activity tab and turn on Live event updates.
Confirm that Sign Up Clicked appears with the plan property.

If the event doesn't appear within a minute, follow Verify events.

Next steps

Set shared and per-product options. Go to Configure each product.
Fetch flags and read variants. Go to Use Feature Experiment.
Turn off Guides and Surveys if you don't use it. Go to Turn off Guides and Surveys.
Track custom events, identify users, and choose autocapture events. Go to the Browser SDK 2 usage guide.

Was this helpful?