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, simplified interface and a lighter weight package.

Browser SDK 2.0 is compatible with Amplitude Session Replay.

Terminology

• @amplitude/marketing-analytics-browser@1: Marketing Analytics 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.

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

Default event tracking

Starting with Browser SDK 2.0, default tracking is enabled by default. Default tracking is implicit tracking performed by Amplitude 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.

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

Additionally, you can pick and choose which events you want tracked by Amplitude. For example, if you only want default tracking for marketing attribution and page views, you can use the code below.

1amplitude.init(API_KEY, undefined, {
2  defaultTracking: {
3    attribution: true,
4    pageViews: true,
5    sessions: false,
6    fileDownload: false,
7    formInteractions: false,
8  },
9});

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 case.

Marketing attribution tracking excludes all subdomains of the same root domain as referrer. This means traffic from one subdomain to another (ie analytics.amplitude.com to experiment.amplitude.com) are not tracked with no additional configuration.

Marketing Analytics Browser SDK by default, allows other subdomains to be tracked as referrer. If this is behavior is desired, refer to the code below.

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

Moved options.attribution to options.defaultTracking.attribution

This consolidates attribution options together with other default tracking options.

1amplitude.init(API_KEY, undefined, {
-  attribution: { 
-    excludeReferrers: [location.hostname]
+  defaultTracking: { 
+    attribution: {
+      excludeReferrers: [location.hostname]
+    },
8  },
9});

Disabling marketing attribution tracking

This provides a simpler and consistent interface to opt out of marketing attribution tracking.

1amplitude.init(API_KEY, undefined, {
-attribution: { 
-    disabled: true
+  defaultTracking: { 
+    attribution: false,
6  },
7});

Page view tracking

The following page view tracking options are changed.

Moved options.pageViewTracking to options.defaultTracking.pageViews

 1amplitude.init(API_KEY, undefined, {
 - pageViewTracking: { 
 -   trackOn: 'attribution',
 -   trackHistoryChanges: 'pathOnly',
 -   eventType: 'Page View',
 + defaultTracking: { 
 +   pageViews: {
 +     trackOn: 'attribution',
 +     trackHistoryChanges: 'pathOnly',
 +     eventType:'Page View',
11 }
12  },
13});

Disable page view tracking

This provides a simpler and consistent interface to opt out of page view tracking.

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

Updates to page view tracking

• The event type of page view has been changed from Page View to [Amplitude] Page Viewed.
• The event properties name also be updated. Check here for more info.

Cookie options

Starting Browser SDK 2.0, Amplitude has simplified the options to manage the use of cookies. By default, user identity is stored on browser cookies.

Using an alternative storage API

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

Disabling user identity persistence

-import { MemoryStorage } from '@amplitude/analytics-core'; 
2 
3amplitude.init(API_KEY, undefined, {
-  cookieStorageProvider: new MemoryStorage(),           
+  identityStorage: 'none',                              
6});

Configuring cookie options

The options to manage cookie usage are now nested under options.cookieOptions for a more discoverable interface.

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

Deprecates user agent client-side parsing

Starting Browser SDK 2.0, Amplitude replaced enrichment of user properties relating to user agent from client-side to server-side. The enriched user properties include os_name, os_version, device_model, device_manufacturer. While the new enrichment strategy yields more accurate results, it also yields slightly different results than Browser SDK 1.0 and may impact your existing analytics charts that query these properties. To prevent this breaking change from impacting you, install @amplitude/plugin-user-agent-enrichment-browser to configure Amplitude to enrich these user properties on the client-side and yield enrichment results similar to Browser SDK 1.0. See NPM for more details.

No enums

Amplitude no longer requires the use of enums specifically TransportType, ServerZone and PluginType, and accepts its literal values.

Setting transport provider on initialization

1import * as amplitude from '@amplitude/analytics-browser';
2 
3amplitude.init(API_KEY, USER_ID, {
-  transport: amplitude.Types.TransportType.Fetch,     
+  transport: 'fetch',                                 
6});

Setting transport provider using setTransport()

1import * as amplitude from '@amplitude/analytics-browser';
2 
-amplitude.setTransport(amplitude.Types.TransportProvider.Fetch); 
+amplitude.setTransport('fetch');                                 

Setting server zone on initialization

1import * as amplitude from '@amplitude/analytics-browser';
2 
3amplitude.init(API_KEY, USER_ID, {
-  serverZone: amplitude.Types.ServerZone.US, 
+  serverZone: 'US',                         
6});

Simplified plugin interface

Amplitude has made it easier to create your own plugins, requiring less properties for faster authoring.

plugin.name [optional]

The name field is an optional property that allows you to reference the plugin for deletion purposes. If not provided, Amplitude will assign a random name when the plugin is added. If you do not plan to delete your plugin, you can skip assigning a name.

plugin.type [optional]

The type field is an optional property that defines the type of plugin you are creating. Refer to execute() function below to distinguish the two types. If not defined, the plugin defaults to an enrichment type.

plugin.setup() [optional]

The setup function is an optional method and is called when the plugin is added or on first init whichever happens later. This function accepts two parameters:

1. Amplitude configuration
2. Amplitude instance

This is useful for setup operations and tasks that depend on either the Amplitude configuration or instance. Examples include assigning baseline values to variables, setting up event listeners, and many more.

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

For enrichment plugins, execute function is an optional method and is called on each event. This function must return a new event, otherwise, the passed event is dropped from the queue. This is useful for cases where you need to add/remove properties from events, filter events, or perform any operation for each event tracked.

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

plugin.teardown() [optional]

The teardown function is an optional method and is called when Amplitude re-initializes. This is useful for resetting unneeded persistent state created/set by setup or execute methods. Examples include removing event listeners, mutation observers, etc.

Web attribution v2 vs web attribution v1