Migrate from Javascript SDK to Browser SDK 2.0

Amplitude Browser SDK 2.0 (@amplitude/analytics-browser@2+) features:

• Plugin architecture
• Built-in type definition
• Broader support for front-end frameworks
• Autocapture
• Improved marketing attribution tracking
• Identical interfaces across platform with other Amplitude SDKs

Browser SDK 2.0 isn't backwards compatible with amplitude-js.

To migrate to @amplitude/analytics-browser@2+, update your dependencies and instrumentation.

Terminology

• amplitude-js: Maintenance Browser SDK
• @amplitude/analytics-browser@2+: Browser SDK 2.0

Dependency

For snippet installation, update your project's snippet loader.

For Node projects, update your dependency list in package.json.

1{
2  "dependencies": {
3    "amplitude-js": "^8"
4  }
5}

1{
2  "dependencies": {
3    "@amplitude/analytics-browser": "^2.11.8"
4  }
5}

Instrumentation

Browser SDK 2.0 offers an API to instrument events. To migrate to the Browser SDK 2.0, update a few calls. The following sections detail which calls have changed.

Initialization

getInstance() has been removed. To initialize the SDK, call init(), with the same parameters. However, config comes in a different shape. See Configuration.

1import amplitude from "amplitude-js"
2 
3amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, config)

1import * as amplitude from "@amplitude/analytics-browser"
2 
3amplitude.init(API_KEY, OPTIONAL_USER_ID, config)

Configuration

Tracking events

The maintenance Browser SDK offered a variety of logEvent APIs like logEventWithTimestamp, logEventWithGroups to override specific properties in the event payload. Instead of these, use the unified track API in @amplitude/analytics-browser@2+.

logEvent()

The logEvent() API maps to track().

1const eventType = "Button Clicked"
2const eventProperties = {
3  type: "primary",
4}
5amplitude.getInstance().logEvent(
6  eventType,
7  eventProperties,
8)

1const eventType = "Button Clicked"
2const eventProperties = {
3  type: "primary",
4}
5amplitude.track(
6  eventType,
7  eventProperties,
8)

logEventWithTimestamp()

The logEventWithTimestamp() API maps to track().

 1const eventType = "Button Clicked"
 2const eventProperties = {
 3  type: "primary",
 4}
 5const timestamp = Date.now()
 6amplitude.getInstance().logEventWithTimestamp(
 7  eventType,
 8  eventProperties,
 9  timestamp,
10)

 1const eventType = "Button Clicked"
 2const eventProperties = {
 3  type: "primary",
 4}
 5const eventOptions = {
 6  time = Date.now()
 7}
 8amplitude.track(
 9  eventType,
10  eventProperties,
11  eventOptions
12)

logEventWithGroups()

The logEventWithGroups() API maps to track().

 1const eventType = "Button Clicked"
 2const eventProperties = {
 3  type: "primary",
 4}
 5const groups = {
 6  orgId: "12345",
 7}
 8amplitude.getInstance().logEventWithGroups(
 9  eventType,
10  eventProperties,
11  groups,
12)

 1const event_type = "Button Clicked"
 2const event_properties = {
 3  type: "primary",
 4}
 5const groups = {
 6  orgId: "12345",
 7}
 8const event = {
 9  event_type,
10  event_properties,
11  groups
12}
13amplitude.track(event)

sendEvents()

The sendEvents() API maps to flush().

1amplitude.getInstance().sendEvents()

1amplitude.flush()

Set user properties

The APIs for setting user properties are the same, except for the removal of getInstance(). Here are code snippets to migrate APIs for user properties.

setUserId()

Set a userId when you invoke amplitude without calling getInstance()

1const userId = "1"
2amplitude.getInstance().setUserId(userId)

1const userId = "1"
2amplitude.setUserId(userId)

setDeviceId()

Set a deviceId when you invoke amplitude without calling getInstance()

1const deviceId = "1"
2amplitude.getInstance().setDeviceId(deviceId)

1const deviceId = "1"
2amplitude.setDeviceId(deviceId)

setSessionId()

Set a sessionId when you invoke amplitude without calling getInstance()

1const sessionId = Date.now()
2amplitude.getInstance().setSessionId(sessionId)

1const sessionId = Date.now()
2amplitude.setSessionId(sessionId)

clearUserProperties()

The clearUserProperties API has been removed. Use the unified identify API to remove user properties.

1amplitude.getInstance().clearUserProperties()

1amplitude.identify(
2  new amplitude.Identify().identify.clearAll()
3)

setUserProperties()

The setUserProperties API has been removed. Use the unified identify API to add user properties.

1amplitude.getInstance().setUserProperties({
2  membership, "paid",
3  payment, "bank",
4})

1const identify = new amplitude.Identify()
2identify
3  .set("membership", "paid")
4  .set("payment", "bank")
5amplitude.identify(identify)

identify()

Make an identify call on amplitude without calling getInstance().

1const identify = new amplitude.Identify()
2identify.set("membership", "paid")
3amplitude.getInstance().identify(identify)

1const identify = new amplitude.Identify()
2identify.set("membership", "paid")
3amplitude.identify(identify)

Set group properties

groupIdentify()

Make an identify call on amplitude without calling getInstance().

1const identify = new amplitude.Identify()
2identify.set("membership", "paid")
3amplitude.getInstance().groupIdentify(identify)

1const identify = new amplitude.Identify()
2identify.set("membership", "paid")
3amplitude.groupIdentify(identify)

Track revenue

logRevenueV2()

Track revenue using revenue() API on amplitude without calling getInstance().

1const revenue = new amplitude.Revenue()
2revenue
3  .setProductId("productId")
4  .setPrice(10)
5amplitude.getInstance().logRevenueV2(revenue)

1const revenue = new amplitude.Revenue()
2revenue
3  .setProductId("productId")
4  .setPrice(10)
5amplitude.revenue(revenue)

Patterns

Plugins

The configs config.language, config.library, config.platform were available in amplitude-js to allow modification of event payloads for these specific fields. Although @amplitude/analytics-browser@2+ doesn't support these configurations, you can add plugins to the new Browser SDK to enrich event payloads.

 1import { BrowserConfig, EnrichmentPlugin, Event, PluginType } from "@amplitude/analytics-types"
 2 
 3export class LibraryModifierPlugin implements EnrichmentPlugin {
 4  name = 'library-modifier'
 5  type = PluginType.ENRICHMENT as const
 6 
 7  /**
 8  * setup() is called on plugin installation
 9  * example: client.add(new LibraryModifierPlugin());
10  */
11  setup(config: BrowserConfig): Promise<undefined> {
12    this.config = config
13  }
14 
15  /**
16  * execute() is called on each event instrumented
17  * example: client.track('New Event');
18  */
19  execute(event: Event): Promise<Event> {
20    event.library = 'my-library-name/1.0.0'
21    return Promise.resolve(event)
22  }
23}

To install your custom plugin, use add() with your custom plugin as a parameter.

1import * as amplitude from '@amplitude/analytics-browser'
2 
3amplitude.add(new LibraryModifierPlugin())
4amplitude.init(API_KEY, OPTIONAL_USER_ID)

Defer initialization

To defer initialization in amplitude-js, call init with config.deferInitialization set to true, and eventually call enableTracking() to formalize initialization and send all enqueued events.

1amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, {
2  deferInitialization: true,
3})
4 
5amplitude.getInstance().logEvent("Event 1")
6amplitude.getInstance().logEvent("Event 2")
7amplitude.getInstance().logEvent("Event 3")
8 
9amplitude.getInstance().enableTracking()

1amplitude.track("Event 1")
2amplitude.track("Event 2")
3amplitude.track("Event 3")
4 
5amplitude.init(API_KEY, OPTIONAL_USER_ID)

Web attribution

In amplitude-js, enable web attribution through the following configurations:

• config.includeGclid
• config.includeFbclid
• config.includeReferrer
• config.includeUtm

In @amplitude/analytics-browser@2+, the single configuration config.autocapture.attribution controls the web attribution. This configuration's default setting is true, and it captures all campaign parameters. These are the same campaign parameters supported in amplitude-js.

Flush or onExitPage

Sometimes you should send events immediately, like when a user navigates away from a page. This is common when tracking button clicks that direct the user to another page while sending event payload in batches.

In amplitude-js do this by using onExitPage() callback.

1amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, {
2  onExitPage: () => {
3    amplitude.sendEvents()
4  },
5})

1window.addEventListener('pagehide', () => {
2  // Set https transport to use sendBeacon API
3  amplitude.setTransport('beacon')
4  // Send all pending events to server
5  amplitude.flush()
6});

Callback

amplitude-js passes one init callback function for executing any function after initialization and two separate callback functions for success and error network requests. With @amplitude/analytics-browser@2+ supporting promises (and async/await), the asynchronous methods like init(), track(), identify(), groupIdentify() return a custom promise interface.

 1const initResult = await amplitude.init("YOUR_API_KEY").promise
 2if (initResult.code === 200) {
 3  // success logic
 4} else {
 5  // error logic
 6}
 7 
 8const result = await amplitude.track("Button Clicked").promise
 9if (result.code === 200) {
10  // success logic
11} else {
12  // error logic
13}