Migrate from Marketing Analytics to Browser SDK 2.0

Amplitude Browser SDK 2.0 (@amplitude/analytics-browser) features default event tracking, improved marketing attribution tracking, a simplified interface, and a lighter weight package.

Browser SDK 2.0 supports Amplitude Session Replay.

Terminology

• @amplitude/marketing-analytics-browser@1: Marketing Analytics Browser SDK.
• @amplitude/analytics-browser@2: Browser SDK 2.0.

Update the dependency

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

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

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

Default event tracking

Starting with Browser SDK 2.0, Amplitude enables default tracking. Default tracking is implicit tracking that Amplitude performs on your behalf, and includes page views, sessions, file downloads, form interactions, and marketing attribution.

To opt out of default tracking, set options.defaultTracking to false.

amplitude.init(API_KEY, undefined, {
  defaultTracking: false,
});

You can also choose which events Amplitude tracks. For example, to enable default tracking only for marketing attribution and page views, use the following code.

amplitude.init(API_KEY, undefined, {
  defaultTracking: {
    attribution: true,
    pageViews: true,
    sessions: false,
    fileDownload: false,
    formInteractions: false,
  },
});

Marketing attribution tracking

Starting with Browser SDK 2.0, Amplitude consolidates Browser SDK and Marketing Analytics SDK to provide a single solution for both product and marketing analytics use cases.

Marketing attribution tracking excludes all subdomains of the same root domain as referrer. Without additional configuration, Amplitude doesn't track traffic from one subdomain to another (for example, analytics.amplitude.com to experiment.amplitude.com).

By default, Marketing Analytics Browser SDK tracks other subdomains as referrer. To preserve this behavior, refer to the following code.

amplitude.init(API_KEY, undefined, {
  defaultTracking: { 
    attribution: {
      excludeReferrers: [location.hostname]
    },
  },
});

Move options.attribution to options.defaultTracking.attribution

Browser SDK 2.0 consolidates attribution options with other default tracking options.

amplitude.init(API_KEY, undefined, {
  attribution: { 
    excludeReferrers: [location.hostname]
  defaultTracking: { 
    attribution: {
      excludeReferrers: [location.hostname]
    },
  },
});

Disable marketing attribution tracking

Browser SDK 2.0 provides a simpler, consistent interface to opt out of marketing attribution tracking.

amplitude.init(API_KEY, undefined, {
attribution: { 
    disabled: true
  defaultTracking: { 
    attribution: false, 
  },
});

Page view tracking

Browser SDK 2.0 changes the following page view tracking options.

Move options.pageViewTracking to options.defaultTracking.pageViews

  amplitude.init(API_KEY, undefined, {
   pageViewTracking: { 
     trackOn: 'attribution',
     trackHistoryChanges: 'pathOnly', 
     eventType: 'Page View',
   defaultTracking: { 
     pageViews: {
       trackOn: 'attribution',
       trackHistoryChanges: 'pathOnly',
       eventType:'Page View',
   }
    },
  });

Disable page view tracking

Browser SDK 2.0 provides a simpler, consistent interface to opt out of page view tracking.

  amplitude.init(API_KEY, undefined, {
   pageViewTracking: false, 
   defaultTracking: { 
     pageViews: false,
    },
  });

Updates to page view tracking

• The page view event type changes from Page View to [Amplitude] Page Viewed.
• The event properties names also update. For more information, refer to Track page views.

Cookie options

Starting with Browser SDK 2.0, Amplitude simplifies the options that manage cookie usage. By default, Amplitude stores user identity in browser cookies.

Use an alternative storage API

amplitude.init(API_KEY, undefined, {
  disableCookies: true,                  
  identityStorage: 'localStorage',       
});

Disable user identity persistence

import { MemoryStorage } from '@amplitude/analytics-core'; 

amplitude.init(API_KEY, undefined, {
  cookieStorageProvider: new MemoryStorage(),           
  identityStorage: 'none',                              
});

Configure cookie options

Browser SDK 2.0 nests the cookie management options under options.cookieOptions for a more discoverable interface.

amplitude.init(API_KEY, undefined, {
  cookieExpiration: 365, 
  cookieSameSite: 'Lax',
  cookieSecure: false,
  cookieUpgrade: true,
  domain: '',
  cookieOptions: {    
    expiration: 365,
    sameSite: 'Lax',
    secure: false,
    upgrade: true,
    domain: '',
  },
});

Deprecates user agent client-side parsing

Starting with Browser SDK 2.0, Amplitude moves user agent enrichment of user properties from client-side to server-side. The enriched user properties include os_name, os_version, device_model, and device_manufacturer. The new enrichment strategy produces more accurate results, but the values differ slightly from Browser SDK 1.0 and may affect existing analytics charts that query these properties. To preserve the previous behavior, install @amplitude/plugin-user-agent-enrichment-browser. The plugin enriches these user properties on the client side and produces results similar to Browser SDK 1.0. For more details, refer to the NPM package.

No enums

Amplitude no longer requires enums (TransportType, ServerZone, and PluginType) and accepts their literal values.

Set the transport provider on initialization.

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

amplitude.init(API_KEY, USER_ID, {
  transport: amplitude.Types.TransportType.Fetch,     
  transport: 'fetch',                                 
});

Set the transport provider using setTransport().

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

amplitude.setTransport(amplitude.Types.TransportProvider.Fetch); 
amplitude.setTransport('fetch');                                 

Set the server zone on initialization.

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

amplitude.init(API_KEY, USER_ID, {
  serverZone: amplitude.Types.ServerZone.US, 
  serverZone: 'US',                         
});

Simplified plugin interface

Amplitude makes plugin creation easier and requires fewer properties for faster authoring.

plugin.name [optional]

The name field is an optional property that lets you reference the plugin for deletion. If you don't provide a name, Amplitude assigns a random name when you add the plugin. If you don't plan to delete the plugin, you can skip the name.

plugin.type [optional]

The type field is an optional property that defines the type of plugin you create. To distinguish the two types, refer to the execute() function. If you don't define a type, the plugin defaults to an enrichment type.

plugin.setup() [optional]

The setup function is an optional method that Amplitude calls when you add the plugin, or on first init, whichever happens later. The function accepts two parameters:

1. Amplitude configuration.
2. Amplitude instance.

The setup function is useful for setup operations and tasks that depend on the Amplitude configuration or instance. Examples include assigning baseline values to variables and setting up event listeners.

plugin.execute() [optional for type: enrichment]

For enrichment plugins, execute is an optional method that Amplitude calls on each event. The function must return a new event, otherwise Amplitude drops the passed event from the queue. The execute function is useful when you need to add or remove properties from events, filter events, or perform any operation for each event tracked.

For destination plugins, execute is a required method that Amplitude calls on each event. The function must return a response object with keys: event (BaseEvent), code (number), and message (string). The execute function is useful for sending events to third-party endpoints.

plugin.teardown() [optional]

The teardown function is an optional method that Amplitude calls when it re-initializes. The teardown function is useful for resetting persistent state created or set by the setup or execute methods. Examples include removing event listeners and mutation observers.

Web attribution v2 vs web attribution v1

Web Attribution V2:

• Enabled by default.
• Tracks attribution on init with a new campaign regardless of session context (new or existing). Not configurable.
• Default value for all initial touch attribution properties is "EMPTY". Configurable with config.initialEmptyValue.
• Doesn't start a new session on new campaign. Configurable with config.resetSessionOnNewCampaign = true.
• Tracks ad click IDs.

Web Attribution V1:

• Enabled by default.
• Tracks attribution on init with a new session. Not configurable.
• Doesn't track attribution on init with a new campaign. Configurable with config.trackNewCampaigns.
• Default value for all initial touch attribution properties is "EMPTY". Configurable with config.initialEmptyValue.
• Doesn't start a new session on new campaign. Configurable with config.resetOnNewCampaign.
• Tracks ad click IDs.