Migrate from Javascript SDK to Browser SDK 1.0

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.

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"
  }
}

Instrumentation

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

Initialization

Like all other calls, Amplitude removed getInstance(). To initialize the SDK, call init() with the same parameters. The config parameter has 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. Amplitude simplified 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);

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 getInstance() no longer exists. The following code snippets show how to migrate user property APIs.

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

Amplitude removed the clearUserProperties API. Use the unified identify API to remove user properties.

amplitude.getInstance().clearUserProperties();

setUserProperties()

Amplitude removed 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

The configs config.language, config.library, and config.platform were available in amplitude-js to modify 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, 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, you enable web attribution by enabling the following configurations:

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

In @amplitude/analytics-browser, a single configuration controls web attribution: config.attribution.disabled. The default value is false, which captures all campaign parameters. This configuration collects the same campaign parameters that amplitude-js supports.

Flush or onExitPage

Some scenarios warrant sending events immediately, such as when a user navigates away from a page. This case is common when tracking 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

In amplitude-js, you pass one init callback function to run after initialization, plus two separate callback functions for success and error network requests. Because @amplitude/analytics-browser supports Promises (and async/await), asynchronous methods such as 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
}