Get started with Browser SDK 2

This guide helps you install Browser SDK 2 (@amplitude/analytics-browser), initialize it, and send one custom event to Amplitude. Each step lists the browser conditions that commonly break that step, so you can fix a problem where it happens. For the full option list, go to Configuration options.

Browser SDK 2 is the analytics-only package. If you also need Session Replay, Feature Experiment, or Guides and Surveys, install the Browser Unified SDK (@amplitude/unified) instead. It includes Browser SDK 2, so don't install both packages on the same page.

Prerequisites

• An Amplitude project and its API key. Find the key in Settings > Projects > your project > General.
• The data center your organization uses: US (default) or EU.
• The latest Browser SDK 2 release, or a pinned version you check against the Browser SDK 2 release notes for the features you use.
• 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

Choose one installation method. Use npm or yarn if you bundle your JavaScript. Use the script loader if you add tags to HTML directly or through a tag manager.

npm install @amplitude/analytics-browser

import * as amplitude from "@amplitude/analytics-browser";

To use the Unified SDK instead, install @amplitude/unified with npm install @amplitude/unified or yarn add @amplitude/unified, and import it the same way:

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

The Unified package exports the same tracking and identity methods, such as track() and setUserId(), but not init(). Call initAll() instead, and pass the analytics options from this guide under analytics:

amplitude.initAll("YOUR_API_KEY", {
  serverZone: "EU", // Omit for US projects.
  analytics: { autocapture: true },
});

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

Fix installation problems

Initialize the SDK

Call init() once, as early as your app has the context it needs, such as a known user ID. Calls you make before init() finishes wait in a queue and run in order after it completes.

amplitude.init("YOUR_API_KEY", {
  autocapture: true,
});

Pass a user ID as the second argument when you already know it:

amplitude.init("YOUR_API_KEY", "user-12345", {
  autocapture: true,
});

If your project uses the EU data center, set serverZone:

amplitude.init("YOUR_API_KEY", {
  serverZone: "EU",
  autocapture: true,
});

autocapture: true turns on every autocapture feature that the SDK enables with a boolean, including element clicks, frustration interactions, failed network requests, and web vitals. To start with only the default set (page views, sessions, attribution, forms, and file downloads), omit autocapture or pass an object. For choices, go to Autocapture.

Fix initialization problems

Send a first event

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

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

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

The SDK uploads queued events about one second after the first one enters the queue, in requests of up to 30 events. The promise resolves after that upload, so expect about one second of delay.

Fix upload problems

Confirm the event in Amplitude

1. In Amplitude, open User Lookup and search for the user ID you passed, or 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. It walks through each stage between track() and Amplitude's servers.

Next steps

• Identify signed-in users with setUserId(), and call reset() when they sign out.
• Choose which Autocapture events to keep.
• Add the custom events and properties your tracking plan needs. Go to Track events.