Browser Unified SDK

Amplitude offers multiple ways to install browser SDKs, each with different product support and version control options. This guide explains the three main installation methods and helps you choose the right approach for your needs.

Choose your installation method

Amplitude provides three main ways to install browser SDKs:

Product support by installation method

Different installation methods support different Amplitude products:

Unified SDK (npm)

The Unified SDK provides a single npm package (@amplitude/unified) giving 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).
• Upgrade by bumping the package version in your dependency file.
• Ideal 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

yarn add @amplitude/unified

You are an Amplitude installation wizard, an expert AI programming assistant that implements Amplitude Analytics, Session Replay, Experiment, and Guides and Surveys for JavaScript-based applications.
Your task is to select, install, and initialize the correct Amplitude package(s) necessary to enable Amplitude Analytics, Session Replay, Experiment, and Guides and Surveys for this application and track key interactions, all in strict accordance to the Documentation provided below.
Rules

Do not make any code changes if this is not a JavaScript-based application
Ensure ALL the code added ONLY runs client-side and never server-side
Ensure amplitude is only initialized once during the lifecycle of the application

Context
Documentation

Install the Amplitude Analytics Browser SDK with npm install @amplitude/unified or yarn add @amplitude/unified
Import amplitude into the root of the client application with import * as amplitude from '@amplitude/unified';
Initialize amplitude with amplitude.initAll('AMPLITUDE_API_KEY', {"analytics":{"autocapture":true},"sessionReplay":{"sampleRate":1},"experiment":{"deploymentKey":"DEPLOYMENT_KEY"},"engagement":{"serverZone":"US","logLevel":LogLevel.Warn}});

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. You can 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

All options from @amplitude/analytics-browser are supported. 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. Set config.sessionReplay.sampleRate to a non-zero value to enable Session Replay.

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

All options from @amplitude/plugin-experiment-browser are supported. 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 remotely controls the versions of the underlying SDKs, 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 are disabled by default and require manual checkbox selection.

Enable Session Replay and Guides & Surveys in GTM

To enable these features:

1. Navigate to your Amplitude tag in GTM.
2. In the tag configuration, check the Session Replay checkbox to enable session replays.
3. Check 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.