Browser SDK Migration Guide

The new version of Amplitude's Browser SDK (@amplitude/analytics-browser) features a plugin architecture, built-in type definition and broader support for front-end frameworks. The new version isn't backwards compatible with amplitude-js.

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

Terminology¶

• amplitude-js: Maintenance Browser SDK
• @amplitude/analytics-browser: New Browser SDK

Dependency¶

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

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

{
  "dependencies": {
    "amplitude-js": "^8"
  }
}

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

Instrumentation¶

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

Initialization¶

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

import amplitude from "amplitude-js"

amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, config)

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

amplitude.init(API_KEY, OPTIONAL_USER_ID, config)

Configuration¶

The new Browser SDK configuration comes in a different shape. The configurations are simpler and more consistent across runtimes. Some configurations are no longer supported.

Tracking events¶

The maintenance Browser SDK offered a variety of logEvent APIs like logEventWithTimestamp, logEventWithGroups to override specific properties in the event payload. Amplitude has simplified all these variations into a unified track API in @amplitude/analytics-browser.

logEvent()¶

The logEvent() API maps to track().

const eventType = "Button Clicked"
const eventProperties = {
  type: "primary",
}
amplitude.getInstance().logEvent(
  eventType,
  eventProperties,
)

const eventType = "Button Clicked"
const eventProperties = {
  type: "primary",
}
amplitude.track(
  eventType,
  eventProperties,
)

logEventWithTimestamp()¶

The logEventWithTimestamp() API maps to track().

const eventType = "Button Clicked"
const eventProperties = {
  type: "primary",
}
const timestamp = Date.now()
amplitude.getInstance().logEventWithTimestamp(
  eventType,
  eventProperties,
  timestamp,
)

const eventType = "Button Clicked"
const eventProperties = {
  type: "primary",
}
const eventOptions = {
  time = Date.now()
}
amplitude.track(
  eventType,
  eventProperties,
  eventOptions
)

logEventWithGroups()¶

The logEventWithGroups() API maps to track().

const eventType = "Button Clicked"
const eventProperties = {
  type: "primary",
}
const groups = {
  orgId: "12345",
}
amplitude.getInstance().logEventWithGroups(
  eventType,
  eventProperties,
  groups,
)

const event_type = "Button Clicked"
const event_properties = {
  type: "primary",
}
const groups = {
  orgId: "12345",
}
const event = {
  event_type,
  event_properties,
  groups
}
amplitude.track(event)

sendEvents()¶

The sendEvents() API maps to flush().

amplitude.getInstance().sendEvents()

amplitude.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()¶

Setting a user ID can be invoked on amplitude without calling getInstance().

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

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

setDeviceId()¶

Setting a device ID can be invoked on amplitude without calling getInstance().

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

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

setSessionId()¶

Set a session ID on amplitude without calling getInstance().

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

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

clearUserProperties()¶

The clearUserProperties API has been removed, but you can now use the unified identify API to remove user properties.

amplitude.getInstance().clearUserProperties()

amplitude.identify(
  new amplitude.Identify().identify.clearAll()
)

setUserProperties()¶

The setUserProperties API has been removed, but you can now use the unified identify API to add user properties.

amplitude.getInstance().setUserProperties({
  membership, "paid",
  payment, "bank",
})

const identify = new amplitude.Identify()
identify
  .set("membership", "paid")
  .set("payment", "bank")
amplitude.identify(identify)

identify()¶

You can now make an identify call on amplitude without calling getInstance().

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

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

Set group properties¶

groupIdentify()¶

You can now make an identify call on amplitude without calling getInstance().

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

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

Tracking revenue¶

logRevenueV2()¶

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

const revenue = new amplitude.Revenue()
revenue
  .setProductId("productId")
  .setPrice(10)
amplitude.getInstance().logRevenueV2(revenue)

const revenue = new amplitude.Revenue()
revenue
  .setProductId("productId")
  .setPrice(10)
amplitude.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 doesn't support these configurations, you can add plugins to the new Browser SDK to enrich event payloads.

import { BrowserConfig, EnrichmentPlugin, Event, PluginType } from "@amplitude/analytics-types"

export class LibraryModifierPlugin implements EnrichmentPlugin {
  name = 'library-modifier'
  type = PluginType.ENRICHMENT as const

  /**
  * setup() is called on plugin installation
  * example: client.add(new LibraryModifierPlugin());
  */
  setup(config: BrowserConfig): Promise<undefined> {
    this.config = config
  }

  /**
  * execute() is called on each event instrumented
  * example: client.track('New Event');
  */
  execute(event: Event): Promise<Event> {
    event.library = 'my-library-name/1.0.0'
    return Promise.resolve(event)
  }
}

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

import { add } from "@amplitude/analytics-browser"

add(new LibraryModifierPlugin())

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.

amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, {
  deferInitialization: true,
})

amplitude.getInstance().logEvent("Event 1")
amplitude.getInstance().logEvent("Event 2")
amplitude.getInstance().logEvent("Event 3")

amplitude.getInstance().enableTracking()

For @amplitude/analytics-browser, you can call init() at a later time than track(). All track() calls are then processed after initialization completes.

amplitude.track("Event 1")
amplitude.track("Event 2")
amplitude.track("Event 3")

amplitude.init(API_KEY, OPTIONAL_USER_ID)

Web attribution¶

In amplitude-js, web attribution is enabled by enabling the following configurations:

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

In @amplitude/analytics-browser, the web attribution is controlled by a single configuration config.attribution.disabled which by default is set to false and captures all campaign parameters. This configuration collects the same campaign parameters supported in amplitude-js.

Flush or onExitPage¶

There are certain scenarios that warrant sending events immediately, like when a user navigates away from a page. This is a common scenario when tracking button clicks that directs the user to another page while sending event payload in batches.

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

amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, {
  onExitPage: () => {
    amplitude.sendEvents()
  },
})

For @amplitude/analytics-browser, Amplitude recommends adding your own event listener for pagehide event.

window.addEventListener('pagehide',
  () => {
    amplitude.setTransport('beacon') // Optional. Sets https transport to use `sendBeacon` API
    amplitude.flush()
  },
);

Callback¶

For amplitude-js, two separate callback functions are passed for success and error. With @amplitude/analytics-browser supporting Promises (and async/await), the asynchronous methods like track(), identify(), groupIdentify() return a custom promise interface.

const result = await amplitude.track("Button Clicked").promise
if (result.code === 200) {
  // success logic
} else {
  // errr logic
}

Still have questions? Ask them in the Community.