Browser Unified SDK

Amplitude offers multiple ways to install browser SDKs, each with different product support and version control options. This guide compares the three main installation methods.

Choose your installation method

Amplitude provides three ways to install browser SDKs:

Product support by installation method

Each installation method supports a different set of Amplitude products:

Unified SDK (npm)

The Unified SDK provides a single npm package (@amplitude/unified) that gives you access to Analytics, Session Replay, Feature Experiment, and Guides & Surveys through a single API. Install it with npm or yarn, and control the version in your package.json.

Key characteristics:

• Customer-managed package installation with full control over versions.
• Includes Feature Experiment (code-based feature flags), not Web Experiment (visual editor).
• To upgrade, bump the package version in your dependency file.
• Best for teams that require reproducible builds and strict change management.

Install the Unified SDK

Install the dependency with npm or yarn.

npm install @amplitude/unified

Initialize the Unified SDK

The Unified SDK provides a single initialization method that initializes all Amplitude features.

import { initAll } from "@amplitude/unified";

initAll("AMPLITUDE_API_KEY");

Access SDK features

The Unified SDK provides access to all Amplitude features through a single interface:

import { track, identify, experiment, sessionReplay } from "@amplitude/unified";

// Track events
track("Button Clicked", { buttonName: "Sign Up" });

// Identify users
identify(new Identify().set("userType", "premium"));

// Access Experiment features
const variant = await experiment.fetch("experiment-key");

// Access Session Replay features
sessionReplay.flush();

Configuration

The Unified SDK supports configuration options for all Amplitude features. Configure each product individually while sharing some common options.

import { initAll } from "@amplitude/unified";

initAll("AMPLITUDE_API_KEY", {
  // Shared options for all SDKs (optional)
  serverZone: "US", // or 'EU'
  instanceName: "my-instance",

  // Analytics options
  analytics: {
    // Analytics configuration options
  },

  // Session Replay options
  sessionReplay: {
    // Session Replay configuration options
    sampleRate: 1, // To enable session replay
  },

  // Experiment options
  experiment: {
    // Experiment configuration options
  },

  // Guides and Surveys options
  engagement: {
    // Guides and Surveys configuration options
  },
});

Shared options

Analytics options

The Unified Browser SDK supports all options from @amplitude/analytics-browser. Refer to the Analytics Browser SDK documentation for details.

Session Replay options

The Unified Browser SDK supports all options from @amplitude/plugin-session-replay-browser. Refer to the Session Replay Plugin documentation for more information. To enable Session Replay, set config.sessionReplay.sampleRate to a non-zero value.

Sample rate controls the rate at which Amplitude captures session replays. For example, if you set config.sessionReplay.sampleRate to 0.5, Session Replay captures roughly half of all sessions.

Experiment options

The Unified Browser SDK supports all options from @amplitude/plugin-experiment-browser. Refer to the Experiment documentation for details.

Guides and Surveys options

The Unified Browser SDK supports all Guides and Surveys options. The engagement plugin initializes automatically when you pass engagement options in the configuration.

Unified script (CDN)

The Unified Script is a single script tag that loads Amplitude browser capabilities from Amplitude's CDN. Amplitude controls the versions of the underlying SDKs remotely, offering a "single line of code" experience with sensible defaults and optional remote or manual configuration.

Key characteristics:

• Amplitude manages SDK versions and can patch bugs or improve performance centrally without requiring a customer release.
• Includes Web Experiment (visual editor) by default.
• Session Replay and Web Experiment enable automatically with default settings.
• Guides & Surveys requires a separate script because of size concerns.

Install the Unified Script

Add the following script tag to the <head> of your site:

<script src="https://cdn.amplitude.com/script/AMPLITUDE_API_KEY.js"></script>

Replace AMPLITUDE_API_KEY with your project's API key.

Initialize the Unified Script

The Unified Script enables Session Replay and Web Experiment by default. For manual configuration:

<script src="https://cdn.amplitude.com/script/AMPLITUDE_API_KEY.js"></script>
<script>
  window.amplitude.init("AMPLITUDE_API_KEY", {
    defaultTracking: true,
    autocapture: true,
    fetchRemoteConfig: true,
  });
  // Enable Session Replay with custom sample rate
  window.amplitude.add(window.sessionReplay.plugin({ sampleRate: 1 }));
</script>

Add Guides & Surveys to the Unified Script

Because of size concerns, Guides & Surveys requires a separate script. Add it after the Unified Script:

<script src="https://cdn.amplitude.com/script/AMPLITUDE_API_KEY.js"></script>
<script src="https://cdn.amplitude.com/script/AMPLITUDE_API_KEY.engagement.js"></script>
<script>
  window.amplitude.add(window.engagement.plugin());
  window.amplitude.init("AMPLITUDE_API_KEY", {
    fetchRemoteConfig: true,
    autocapture: true,
  });
</script>

Refer to the Guides and Surveys SDK documentation for more configuration options.

Google Tag Manager

The Amplitude GTM template directly wraps the Analytics Browser 2.0 SDK (@amplitude/analytics-browser). It doesn't use the Unified SDK or Unified Script.

Key characteristics:

• Template version-controlled through GTM.
• Supports Analytics, Session Replay, and Guides & Surveys.
• Doesn't support Web Experiment or Feature Experiment.
• Session Replay and Guides & Surveys default to disabled and require manual checkbox selection.

Enable Session Replay and Guides & Surveys in GTM

To enable these features:

1. Go to your Amplitude tag in GTM.
2. In the tag configuration, select the Session Replay checkbox to enable session replays.
3. Select the Guides & Surveys checkbox to enable in-product messaging.
4. Save and publish your changes.

Refer to the Google Tag Manager documentation for detailed configuration options.