---
title: Get started with the Browser Unified SDK
description: "Install the Amplitude Browser Unified SDK, initialize Analytics, Session Replay, Feature Experiment, and Guides and Surveys with one call, and send a first event."
product: analytics
lang: en
last_updated: 2026-10-29
token_estimate: 1899
---
# Get started with 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`.

- **Package:** `@amplitude/unified` ([npm](https://www.npmjs.com/package/@amplitude/unified))
- **Latest version:** 1.1.43

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

The Unified SDK bundles [Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/get-started) (`@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](https://amplitude.com/docs/sdks/analytics/browser/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](https://amplitude.com/docs/sdks/analytics/browser/choose-a-browser-installation#unified-script-cdn).
- 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

#### npm

```bash
npm install @amplitude/unified
```

#### yarn

```bash
yarn add @amplitude/unified
```

#### AI prompt

Use the getting started prompt generator to create an installation prompt with your Amplitude API key and selected setup options.

Then import the package:

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

```ts
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](https://amplitude.com/docs/sdks/frameworks/nextjs-installation-guide). |

For analytics initialization problems, such as cookies or autocapture warnings, go to [Fix initialization problems](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/get-started#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.

```ts
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](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/get-started#fix-upload-problems) in Browser SDK 2.

## Confirm the event in Amplitude

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

If the event doesn't appear within a minute, follow [Verify events](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/verify-events).

## Next steps

- Set shared and per-product options. Go to [Configure each product](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/instrument-and-configure#configure-each-product).
- Fetch flags and read variants. Go to [Use Feature Experiment](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/instrument-and-configure#use-feature-experiment).
- Turn off Guides and Surveys if you don't use it. Go to [Turn off Guides and Surveys](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk/instrument-and-configure#turn-off-guides-and-surveys).
- Track custom events, identify users, and choose autocapture events. Go to the [Instrument and configure Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/instrument-and-configure).