Migrate from Browser SDK 1.0 to 2.0

Amplitude Browser SDK 2.0 (@amplitude/analytics-browser) features Autocapture, improved marketing attribution tracking, a simplified interface, and a lighter-weight package.

Browser SDK 2.0 is compatible with Amplitude Session Replay.

Terminology

• @amplitude/analytics-browser@1: Browser SDK 1.0
• @amplitude/analytics-browser@2: Browser SDK 2.0

Dependency

{
  "dependencies": {
-   "@amplitude/analytics-browser": "^1"
+   "@amplitude/analytics-browser": "^2"
  }
}

Autocapture

Starting with Browser SDK 2.10.0, Amplitude enables Autocapture by default. Autocapture is implicit tracking that Amplitude performs on your behalf, and includes page views, sessions, file downloads, form and element interactions, and marketing attribution.

To opt out of default tracking, set options.autocapture to false.

amplitude.init(API_KEY, undefined, {
  autocapture: false,
});

You can also select which events Amplitude tracks. For example, to enable default tracking only for marketing attribution and page views, use the code below.

amplitude.init(API_KEY, undefined, {
  autocapture: {
    attribution: true,
    pageViews: true,
    sessions: false,
    fileDownload: false,
    formInteractions: false,
    elementInteractions: false,
  },
});

Marketing attribution tracking

Starting with Browser SDK 2.0, Amplitude consolidates Browser SDK and Marketing Analytics SDK into a single solution for both product and marketing analytics use cases.

Marketing attribution tracking excludes all subdomains of the same root domain as referrer. By default, Amplitude doesn't track traffic from one subdomain to another (for example, analytics.amplitude.com to experiment.amplitude.com).

By default, Browser SDK 1.0 tracks other subdomains as referrer. To preserve this behavior, refer to the code below.

Deprecates options.attribution.trackNewCampaigns

This option is no longer supported because Amplitude adopted it as non-configurable default behavior. Amplitude tracks any changes to campaign parameters, which includes UTM, referrer, and click ID parameters.

Deprecates options.attribution.trackPageViews

This option no longer exists, but you can configure Amplitude similarly using page view options.

amplitude.init(API_KEY, undefined, {
- attribution: {
-   trackPageViews: true,
- },
+ defaultTracking: {
+   pageViews: {
+     trackOn: 'attribution',
+   },
+ },
});

Cookie options

Starting with Browser SDK 2.0, Amplitude simplified the options that manage cookie use. By default, Amplitude stores user identity in browser cookies.

Using an alternative storage API

amplitude.init(API_KEY, undefined, {
  disableCookies: true,
  identityStorage: "localStorage",
});

Disabling user identity persistence

import { MemoryStorage } from "@amplitude/analytics-core";

amplitude.init(API_KEY, undefined, {
  cookieStorageProvider: new MemoryStorage(),
  identityStorage: "none",
});

Configuring cookie options

The options that manage cookie usage now nest under options.cookieOptions for a more discoverable interface.

amplitude.init(API_KEY, undefined, {
  cookieExpiration: 365,
  cookieSameSite: "Lax",
  cookieSecure: false,
  cookieUpgrade: true,
  domain: "",
  cookieOptions: {
    expiration: 365,
    sameSite: "Lax",
    secure: false,
    upgrade: true,
    domain: "",
  },
});

Deprecates user agent client-side parsing

Starting with Browser SDK 2.0, Amplitude moved user agent property enrichment from client-side to server-side. The enriched user properties include os_name, os_version, device_model, and device_manufacturer. The new enrichment strategy yields more accurate results, but it produces slightly different results than Browser SDK 1.0 and may affect existing analytics charts that query these properties. To preserve Browser SDK 1.0 behavior, install @amplitude/plugin-user-agent-enrichment-browser to enrich these user properties on the client-side. Refer to the plugin-user-agent-enrichment-browser package on NPM for more details.

No enums

Amplitude no longer requires the enums TransportType, ServerZone, and PluginType, and accepts their literal values.

Set the transport provider on initialization:

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

amplitude.init(API_KEY, USER_ID, {
  transport: amplitude.Types.TransportType.Fetch,
  transport: "fetch",
});

Set the transport provider using setTransport():

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

amplitude.setTransport(amplitude.Types.TransportProvider.Fetch);
amplitude.setTransport("fetch");

Set the server zone on initialization:

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

amplitude.init(API_KEY, USER_ID, {
  serverZone: amplitude.Types.ServerZone.US,
  serverZone: "US",
});

Simplified plugin interface

Amplitude makes it easier to create your own plugins, requiring fewer properties for faster authoring.

plugin.name [optional]

The name field is an optional property that lets you reference the plugin for deletion. If you don't provide a name, Amplitude assigns a random name when you add the plugin. If you don't plan to delete your plugin, you can skip assigning a name.

plugin.type [optional]

The type field is an optional property that defines the type of plugin you're creating. Refer to the execute() function below to distinguish the two types. If you don't define a type, the plugin defaults to an enrichment type.

plugin.setup() [optional]

The setup function is an optional method that Amplitude calls when you add the plugin, or on first init, whichever happens later. This function accepts two parameters:

1. Amplitude configuration.
2. Amplitude instance.

The setup function is useful for setup operations and tasks that depend on either the Amplitude configuration or instance. Examples include assigning baseline values to variables and setting up event listeners.

plugin.execute() [optional for type: enrichment]

For enrichment plugins, the execute function is an optional method that Amplitude calls on each event. This function must return a new event. Otherwise, Amplitude drops the passed event from the queue. The execute function is useful when you need to add or remove properties from events, filter events, or perform any operation for each event tracked.

For destination plugins, the execute function is a required method that Amplitude calls on each event. This function must return a response object with keys: event (BaseEvent), code (number), and message (string). The execute function is useful for sending events to third-party endpoints.

plugin.teardown() [optional]

The teardown function is an optional method that Amplitude calls when Amplitude re-initializes. The teardown function is useful for resetting unneeded persistent state that the setup or execute methods created. Examples include removing event listeners and mutation observers.

Web attribution v2 vs web attribution v1

Web Attribution V2:

• Enabled by default.
• Tracks attribution on init with a new campaign regardless of session context (new or existing). Not configurable.
• Default value for all initial touch attribution properties is "EMPTY". Configurable with config.initialEmptyValue.
• Doesn't start a new session on new campaign. Configurable with config.resetSessionOnNewCampaign = true.
• Tracks ad click IDs.

Web Attribution V1:

• Enabled by default.
• Tracks attribution on init with a new session. Not configurable.
• Doesn't track attribution on init with a new campaign. Configurable with config.trackNewCampaigns.
• Default value for all initial touch attribution properties is "EMPTY". Configurable with config.initialEmptyValue.
• Doesn't start a new session on new campaign. Configurable with config.resetOnNewCampaign.
• Tracks ad click IDs.