Skip to content

Browser SDK Migration Guide

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

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

Browser SDK 2.0 is now available

An improved version of Amplitude Browser SDK is now available. Amplitude Browser SDK 2.0 features default event tracking, improved marketing attribution tracking, simplified interface and a lighter weight package. Amplitude recommends the Browser SDK 2.0 for both product analytics and marketing analytics use cases. Upgrade to the latest Browser SDK 2.0. See the Migration Guide for more help.

Terminology

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

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

Browser SDK 1.0 offers an API to instrument events. To migrate to the Browser SDK 1.0, 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.

amplitude-js @amplitude/analytics-browser
config.apiEndpoint config.serverUrl
config.batchEvents config.flushQueueSize
config.cookieExpiration config.cookieExpiration
config.cookieName NOT SUPPORTED
config.sameSiteCookie config.cookieSameSite
config.cookieForceUpgrade NOT SUPPORTED
config.deferInitialization NOT SUPPORTED. See Defer initialization.
config.disableCookies config.disableCookies
config.deviceId config.deviceId
config.deviceIdFromUrlParam NOT SUPPORTED
config.domain NOT SUPPORTED
config.eventUploadPeriodMillis config.flushIntervalMillis
config.eventUploadThreshold config.flushQueueSize
config.forceHttps NOT SUPPORTED
config.includeFbclid NOT SUPPORTED. See Web attribution.
config.includeGclid NOT SUPPORTED. See Web attribution.
config.includeReferrer NOT SUPPORTED. See Web attribution.
config.includeUtm NOT SUPPORTED. See Web attribution.
config.language NOT SUPPORTED. See Plugins.
config.library NOT SUPPORTED. See Plugins.
config.logLevel config.logLevel
config.logAttributionCapturedEvent NOT SUPPORTED
config.optOut config.optOut
config.onError NOT SUPPORTED
config.onExitPage NOT SUPPORTED. See Flush.
config.platform NOT SUPPORTED. platform is not supported at configuration level. But it still exist in event object. You can overwrite this by either assign a platform while tracking an event, or enriching the event.platform using enrichment plugin. See Plugins.
config.savedMaxCount NOT SUPPORTED
config.saveEvents NOT SUPPORTED
config.saveParamsReferrerOncePerSession config.attribution.trackNewCampaigns. Opposite of saveParamsReferrerOncePerSession. See configuration.
config.secureCookie config.cookieSecure
config.sessionTimeout config.sessionTimeout
config.storage config.storageProvider
config.trackingOptions config.trackingOptions
config.transport config.transportProvider
config.unsetParamsReferrerOnNewSession NOT SUPPORTED. Default behavior.
config.unsentKey NOT SUPPORTED
config.unsentIdentifyKey NOT SUPPORTED
config.uploadBatchSize config.flushQueueSize
config.headers NOT SUPPORTED
config.serverZone config.serverZone
config.useDynamicConfig NOT SUPPORTED
config.serverZoneBasedApi NOT SUPPORTED
config.sessionId config.sessionId
config.partnerId config.partnerId

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()

Id length limit

The maintenance SDK uses an old SDK endpoint (api2.amplitude.com) which enforces no length limit for deviceId and userId. The latest SDK uses Amplitude's HTTP V2 API (api2.amplitude.com/2/httpapi) and requires identifiers to be at least 5 characters by default. When you migrate to the latest SDK, set config.minIdLength to a smaller value if you allowed identifiers with fewer than 5 characters.

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()

Id length limit

The maintenance SDK uses an old SDK endpoint (api2.amplitude.com) which enforces no length limit for deviceId and userId. The latest SDK uses Amplitude's HTTP V2 API (api2.amplitude.com/2/httpapi) and requires identifiers to be at least 5 characters by default. When you migrate to the latest SDK, set config.minIdLength to a smaller value if you allowed identifiers with fewer than 5 characters.

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', () => {
  // Set https transport to use sendBeacon API
  amplitude.setTransport('beacon')
  // Send all pending events to server
  amplitude.flush()
});

Callback

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

const initResult = await amplitude.init("YOUR_API_KEY").promise
if (initResult.code === 200) {
  // success logic
} else {
  // error logic
}

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

Comparison

This section provides a comparison between different version of SDKs. This overview provides key insights for developers, identifying areas that have significant changes and need careful consideration.

Note

While there are multiple versions of our SDK available, please use the latest version of the SDKs rather than maintenance SDKs. Maintenance versions only provide support and will eventually be deprecated. The latest SDK adopts an aligned architecture, with no extra dependencies, and offers enhanced stability for optimal performance.

Feature Maintenance Browser SDK
Package @amplitude/analytics-browser @amplitude/marketing-analytics-browser amplitude-js
Web Attribution 1 By default, the Browser SDK includes the web-attribution plugin which implements Web Attribution V1. Configuration required. Use Web Attribution V2. Configuration required. Use Maintenance Web Attribution.
Default Event Tracking 2 Default Event Tracking V2 Default Event Tracking V1 Not supported.
Configuration Configuration is implemented by Configuration object during initialize amplitude. More configurations. Check here for migration guide from the Maintenance SDK to the latest SDK. The same as latest Browser SDK. Support explicit setter methods. More configurations.
Logger provider Amplitude Logger by Default. Fully customizable. The same as latest Browser SDK. Amplitude Logger by default. Not customizable.
Storage Provider LocalStorage by default. Fully customizable. The same as latest Browser SDK. Limited storage - cookies, localStorage, sessionStorage, or none available. Not able to be customized.
Customization Plugins Plugins Not supported. (Middleware is supported in Ampli JS)
Bundle Size Tree shaking for optimization. The same as latest Browser SDK. No Optimization.
Server Endpoint HTTP V2 API The same as latest Browser SDK. HTTP V1 API
Batch API Supported, with configuration. The same as latest Browser SDK. Not supported.

Default Event Tracking V2 vs Default Event Tracking V1

Feature
Default Event Tracking V2
Default Event Tracking V1
Configurable Yes. Enable by setting config.defaultTracking configuration. More Details. Yes. Enable by setting config.pageViewTracking configuration. More Details.
Events Includes with configuration
  • page view event([Amplitude] Page viewed)
  • sessions events([Amplitude] Session Start, [Amplitude] Session End)
  • form interactions events([Amplitude] Form Started, [Amplitude] Form Submitted, [Amplitude] Form Downloaded)
Includes with configuration
  • page view event (Page view)
Architecture Implemented through different plugins. Implemented through page-view-tracking plugin.
Customizable Yes. Through Enrichment Plugin. Yes. Through Enrichment Plugin.

Web Attribution V2 vs Web Attribution V1 vs Maintenance Web Attribution

Configurable

Web Attribution V2
Web Attribution V1
Maintenance Web Attribution
No. Yes. Yes.

Behavior

Web Attribution V2
Web Attribution V1
Maintenance Web Attribution
  • Enabled by default.
  • This SDK tracks attribution on init with a new campaign no matter if a new session or during a session and NOT configurable.
  • Default value for all init attribution is Empty and configurable.
  • If reset session ID on new campaign is configurable.
  • Collect all latest ClickIds.
  • Enabled by default.
  • The SDK track web attribution on init with a new session by default. This SDK tracks attribution on init with a new campaign is disable by default and configurable with config.trackNewCampaigns = true. If tracking web attribution on init with a new campaign is enable, the campaign will be unset (set to none) if that attribution not included.
  • Default value for all init attribution is Empty and configurable.
  • If reset session ID on new campaign is configurable.
  • Collect all latest ClickIds.
  • Disable by default.
  • This SDK tracks attribution on init with a new session by default. This SDK tracks attribution on init during a session is disable by default and configurable with config.saveParamsReferrerOncePerSession = false. By default the existing web attribution values will be carried through each new session. Unless you set config.unsetParamsReferrerOnNewSession = true, web attribution will be set to null upon instantiating a new session.
  • It only track the init attribution which has value.
  • Cannot set session ID on campaign.
  • Only collect gclid and fbclid ClickIds.

Workflow

Web Attribution V2 Web Attribution V1 Maintenance Web Attribution
Web Attribution V2 Web Attribution V1 Maintenance Web Attribution

Architecture

Web Attribution V2
Web Attribution V1
Maintenance Web Attribution
Implemented through web-attribution Plugin. Implemented through web-attribution Plugin. Build in logic.

  1. Web Attribution: For Browser SDK version lower than 1.9.0, you are able to choose if use Web Attribution V1 or use Web Attribution V2. For using Web Attribution V2 you need to disable the Web Attribution V1 by setting config.attribution.disabled = false, install the @amplitude/plugin-web-attribution-browser and add web-attribution plugin manually, which will lead web attribution behavior the same as Marketing Analytics Browser SDK. 

  2. Default Event Tracking: For Browser SDK version lower than 1.9.0, to track page view events, you need to install the npm install @amplitude/plugin-page-view-tracking-browser and add page-view-tracking plugin manually. The event name for page views, along with the event properties for page views are different than the latest default event tracking. 


Was this page helpful?