Migrate from Javascript SDK to Browser SDK 2.0

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

• Plugin architecture.
• Built-in type definition.
• Broader support for front-end frameworks.
• Autocapture.
• Improved marketing attribution tracking.
• Identical interfaces across platforms 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.

this.init("API_KEY", {
  deviceId: "device_id",
  userId: "user_id",
});

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.

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

Instrumentation

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

Initialization

Browser SDK 2.0 removes getInstance(). To initialize the SDK, call init() with the same parameters. The config object uses a different shape. Refer to Configuration.

import amplitude from "amplitude-js";

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

Configuration

Tracking events

The maintenance Browser SDK offered several logEvent APIs, such as logEventWithTimestamp and logEventWithGroups, to override specific properties in the event payload. In @amplitude/analytics-browser@2+, use the unified track API instead.

logEvent()

The logEvent() API maps to track().

const eventType = "Button Clicked";
const eventProperties = {
  type: "primary",
};
amplitude.getInstance().logEvent(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);

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

sendEvents()

The sendEvents() API maps to flush().

amplitude.getInstance().sendEvents();

Set user properties

The APIs for setting user properties are the same, except that getInstance() is no longer required. The following code snippets show how to migrate APIs for user properties.

setUserId()

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

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

setDeviceId()

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

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

setSessionId()

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

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

clearUserProperties()

Browser SDK 2.0 removes the clearUserProperties API. Use the unified identify API to remove user properties.

amplitude.getInstance().clearUserProperties();

setUserProperties()

Browser SDK 2.0 removes the setUserProperties API. Use the unified identify API to add user properties.

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

identify()

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

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

Set group properties

groupIdentify()

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

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

Track 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);

Patterns

Plugins

In amplitude-js, the configs config.language, config.library, and config.platform let you modify 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.

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 a parameter.

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

amplitude.add(new LibraryModifierPlugin());
amplitude.init(API_KEY, OPTIONAL_USER_ID);

Defer initialization

To defer initialization in amplitude-js, call init with config.deferInitialization set to true, then 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();

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 web attribution. The default setting is true, and it captures all campaign parameters. These are the same campaign parameters that amplitude-js supports.

Flush or onExitPage

Sometimes you need to send events immediately, such as when a user navigates away from a page. Immediate sending is common when you track button clicks that direct the user to another page while sending event payloads in batches.

In amplitude-js, use the onExitPage() callback.

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

Callback

amplitude-js accepts one init callback function to run after initialization, plus two separate callback functions for success and error network requests. Because @amplitude/analytics-browser@2+ supports promises and async/await, asynchronous methods like init(), track(), identify(), and 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
}