Marketing Analytics Browser (Maintenance)

The Marketing Analytics Browser SDK extends the Browser SDK to identify users and events based on marketing channels. This library is open-source, check it out on GitHub.

Getting started¶

Installation¶

To get started with using Marketing Analytics Browser SDK, install the package in your project via NPM or script loader.

Install as Node package¶

This package is available on NPM registry and you can install it using npm or yarn.

npm install @amplitude/marketing-analytics-browser

yarn add @amplitude/marketing-analytics-browser

Use script loader¶

This package is also distributed through a CDN. Copy and paste this script in your HTML file.

<script type="text/javascript">
!function(){"use strict";!function(e,t){var r=e.amplitude||{_q:[],_iq:[]};if(r.invoked)e.console&&console.error&&console.error("Amplitude snippet has been loaded.");else{var n=function(e,t){e.prototype[t]=function(){return this._q.push({name:t,args:Array.prototype.slice.call(arguments,0)}),this}},s=function(e,t,r){return function(n){e._q.push({name:t,args:Array.prototype.slice.call(r,0),resolve:n})}},o=function(e,t,r){e[t]=function(){if(r)return{promise:new Promise(s(e,t,Array.prototype.slice.call(arguments)))}}},i=function(e){for(var t=0;t<m.length;t++)o(e,m[t],!1);for(var r=0;r<y.length;r++)o(e,y[r],!0)};r.invoked=!0;var a=t.createElement("script");a.type="text/javascript",a.integrity="sha384-PPfHw98myKtJkA9OdPBMQ6n8yvUaYk0EyUQccFSIQGmB05K6aAMZwvv8z50a5hT2",a.crossOrigin="anonymous",a.async=!0,a.src="https://cdn.amplitude.com/libs/marketing-analytics-browser-0.3.2-min.js.gz",a.onload=function(){e.amplitude.runQueuedFunctions||console.log("[Amplitude] Error: could not load SDK")};var c=t.getElementsByTagName("script")[0];c.parentNode.insertBefore(a,c);for(var u=function(){return this._q=[],this},p=["add","append","clearAll","prepend","set","setOnce","unset","preInsert","postInsert","remove","getUserProperties"],l=0;l<p.length;l++)n(u,p[l]);r.Identify=u;for(var d=function(){return this._q=[],this},v=["getEventProperties","setProductId","setQuantity","setPrice","setRevenue","setRevenueType","setEventProperties"],f=0;f<v.length;f++)n(d,v[f]);r.Revenue=d;var m=["getDeviceId","setDeviceId","getSessionId","setSessionId","getUserId","setUserId","setOptOut","setTransport","reset"],y=["init","add","remove","track","logEvent","identify","groupIdentify","setGroup","revenue","flush"];i(r),r.createInstance=function(){var e=r._iq.push({_q:[]})-1;return i(r._iq[e]),r._iq[e]},e.amplitude=r}}(window,document)}();

amplitude.init("YOUR_API_KEY_HERE");
</script>

Usage¶

The Marketing Analytics Browser SDK has the same functionalities as the Browser SDK. For the basic usage, check out the Browser SDK docs.

Configuration¶

Basic configuration options are the same as the standard Browser SDK.

In addition to the basic configuration options, the Marketing Analytics Browser SDK has options to configure web attribution and page view tracking.

Configure batching behavior¶

To support high-performance environments, the SDK sends events in batches. Every event logged by the track method is queued in memory. Events are flushed in batches in background. You can customize batch behavior with flushQueueSize and flushIntervalMillis. By default, the serverUrl will be https://api2.amplitude.com/2/httpapi. For customers who want to send large batches of data at a time, set useBatch to true to set setServerUrl to batch event upload API https://api2.amplitude.com/batch. Both the regular mode and the batch mode use the same events upload threshold and flush time intervals.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  // Events queued in memory will flush when number of events exceed upload threshold
  // Default value is 30
  flushQueueSize: 50, 
  // Events queue will flush every certain milliseconds based on setting
  // Default value is 10000 milliseconds
  flushIntervalMillis: 20000,
  // Using batch mode with batch API endpoint, `https://api2.amplitude.com/batch`
  useBatch: true
});

EU data residency¶

You can configure the server zone when initializing the client for sending data to Amplitude's EU servers. The SDK sends data based on the server zone if it's set.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  serverZone: 'EU',
});

Marketing attribution¶

Amplitude tracks marketing attribution to identify your user's traffic source using the UTM, referrer and click ID parameters.

UTM parameters¶

UTM (Urchin Traffic Monitor) parameters are useful for analyzing the effectiveness of different ad campaigns and referring sites. UTM parameters are case-sensitive, so they're treated as different values when the capitalization varies.

There are five different standard UTM parameters:

Here is an example URL with UTM parameters:

https://www.amplitude.com/?utm_source=newsletter&utm_campaign=product_analytics_playbook&utm_medium=email&utm_term=product%20analytics&utm_content=banner-link

Referrer parameters¶

Referrer is the URL of the page that linked to the destination page. Amplitude tracks the following parameters:

Referrer is an empty string ('') if the user navigated to the destination page directly.

Click ID parameters¶

Click IDs are campaign identifiers included as URL query parameters. Ad platforms use these IDs to identify the campaign and other attributes. While Amplitude doesn't have access to further campaign attributes associated to Click IDs, Amplitude can track Click ID values specified in the following table.

First-touch attribution¶

Amplitude captures the initial attribution data at the start of the first session. The first-touch attribution values are set when a user's attribution data are seen for the first time. The following user properties are set one time:

• initial_utm_source
• initial_utm_medium
• initial_utm_campaign
• initial_utm_term
• initial_utm_content
• initial_referrer
• initial_referring_domain
• initial_gclid
• initial_fbclid
• initial_dclid
• initial_gbraid
• initial_ko_click_id
• initial_msclkid
• initial_ttclid
• initial_twclid
• initial_wbraid
• initial_li_fat_id
• initial_rdt_cid

Multi-touch attribution¶

Amplitude captures the attribution data at the start of each session, and sets those values as user properties. For organic or direct traffic, these properties may not be available. Therefore, these user properties are unset from user identity.

For every new campaign (when new attribution data is seen), Amplitude captures the changes regardless of the state of the user session. You can configure resetSessionOnNewCampaign to true to reset the session on every new campaign. The default behavior is to not reset the session on new campaign.

Amplitude tracks the following as user properties:

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content
• referrer
• referring_domain
• gclid
• fbclid
• dclid
• gbraid
• ko_click_id
• msclkid
• ttclid
• twclid
• wbraid
• li_fat_id
• rdt_cid

For users who initially visits a page directly or organically, by default, the initial value is set to "EMPTY". If you prefer a different initial value, set attribution.initialEmptyValue to any string value.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  attribution: {
    initialEmptyValue: 'none',
  }
});

Exclude the referrers from specific domain¶

You can configure Amplitude to opt out of collection of attribution data for a given list of referrers.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  attribution: {
    excludeReferrers: ['www.test.com'],
  }
});

Reset the session on a new campaign¶

You can configure Amplitude to start a new session if any campaign parameter changes. Do this by setting attribution.resetSessionOnNewCampaign to true. By default attribution.resetSessionOnNewCampaign is set to false.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  attribution: {
    resetSessionOnNewCampaign: true,
  }
});

Disable attribution tracking¶

You can configure Amplitude to opt out of automatic collection of attribution data. Do this by setting attribution.disabled to true. By default attribution.disabled is set to false.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  attribution: {
    disabled: true,
  }
});

Page view¶

Enable page view tracking by setting pageViewTracking to true. The page view event is fired when the page loads.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  pageViewTracking: true
});

You can set pageViewTracking to an object to pass more options.

Track the page view event when the attribution changed¶

Set the trackOn option to 'attribution' to send Page View events only when attribution information changes.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  pageViewTracking: {
    trackOn: 'attribution',
  }
});

Track the page view event based on specific criteria¶

trackOn can also be set to a function callback to fully customize when a Page View event is sent.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  pageViewTracking: {
    trackOn: () => {
      return window.location.pathname === '/landing_page'
    },
  }
});

Single page app page view tracking¶

If you have a single page app that uses a history based router such as react-router, you can enable trackHistoryChanges to send Page View events when users navigate between pages. Possible values for trackHistoryChanges:

You can set the trackHistoryChanges to pathOnly to only track the on path changes. By default, full page URL is considered into the page view changes.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  pageViewTracking: {
    trackHistoryChanges: 'pathOnly' // or 'all'
  }
});

The following information is tracked in the page view events.

Use the Marketing Analytics SDK with Ampli¶

You can use Ampli with this SDK by passing an instance of the Marketing Analytics SDK to ampli.load(). See the Ampli documentation for the Browser SDK for more details on configuration.

1. Add the Marketing Analytics Browser SDK to your project.
2. Create an instance of the SDK.
3. Pass the instance into ampli.load()

This example passes the "amplitude" instance to ampli.load.

amplitude.init(REACT_APP_AMPLITUDE_API_KEY, undefined, { ...DefaultConfiguration, logLevel: 3 });
ampli.load({ 
  client: { 
    instance: amplitude 
  } 
});