Marketing Analytics Browser
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.
Marketing Analytics Browser SDK Resources
Marketing Analytics Browser SDK versus the Browser SDK
The Marketing Analytics Browser SDK extends the Browser SDK with automatic web attribution and page view tracking. This doc only includes the configuration related with web attribution and page view tracking. For other functionality check the Browser SDK.
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.
Configuration Options
Name |
Description | Default Value |
---|---|---|
apiKey |
Required. string . The apiKey of your project. |
null |
flushIntervalMillis |
number . The amount of time waiting to upload the event to the server in millionseconds. |
1 second. |
flushQueueSize |
number . The maximum number of events that can be stored locally before forcing an upload. |
30 events. |
flushMaxRetries |
number . The max retry limits. |
5 times. |
logLevel |
LogLevel.None or LogLevel.Error or LogLevel.Warn or LogLevel.Verbose or LogLevel.Debug . The log level. |
LogLevel.Warn |
loggerProvider |
Logger . Implements a custom loggerProvider class from the Logger, and pass it in the configuration during the initialization to help with collecting any error messages from the SDK in a production environment. |
Amplitude Logger |
minIdLength |
number . Overrides the minimum length of user_id & device_id fields. |
5 |
optOut |
boolean . If optOut is true , the event isn't sent to Amplitude's servers. |
false |
serverUrl |
string . The server url events upload to. |
https://api2.amplitude.com/2/httpapi |
serverZone |
EU or US . Set Amplitude Server Zone, switch to zone related configuration. To send data to Amplitude's EU servers should configure to EU |
US |
storageProvider |
Storage<Event[]> . Implements a custom storageProvider class from Storage. |
MemoryStorage |
useBatch |
boolean . When true , uses the Batch API instead of the HTTP V2 API. |
false |
transportProvider |
Transport . Custom HTTP client. For example, sending requests to your proxy server with customized HTTP request headers. |
Transport |
transport |
TransportType.XHR or TransportType.SendBeacon or TransportType.Fetch . Set the transport type. |
TransportType.Fetch |
appVersion |
string . The current version of your application. For example: "1.0.0" |
null |
deviceId |
string . A device-specific identifier. |
UUID() |
cookieExpiration |
number . The days when the cookie expires. |
365 days. |
cookieSameSite |
string . The SameSite attribute of the Set-Cookie HTTP response header. |
LAX |
cookieSecure |
boolean . If restrict access to cookies or not. A cookie with the Secure attribute is only sent to the server with an encrypted request over the HTTPS protocol. |
false |
cookieStorage |
Storage<UserSession> . Implements a custom cookieStorage class from Storage . |
MemoryStorage<UserSession> |
disableCookies |
boolean . If disable cookies or not. If cookies is disable, using LocalStorage or MemoryStorage. |
The cookies is enable by default. |
domain |
string . Set the top level domain. |
null |
partnerId |
string . The partner Id value. Amplitude requires the customer who built an event ingestion integration to add the partner identifier to partner_id . |
null |
sessionManager |
SessionManager . Implements a custom sessionManager class from SessionManager . |
SessionManager(new MemoryStorage<UserSession>(), '') |
sessionTimeout |
number . How long one session expire. |
30 minutes. |
userId |
number . ID for the user. Must have a minimum length of 5 characters unless overridden with the min_user_length option. |
undefined |
config.trackingOptions |
TrackingOptions . Please check the Optional tracking section for more tracking options configuration. |
Enable all tracking options by default. |
In addition to the basic configuration options, the Marketing Analytics Browser SDK has options to configure web attribution and page view tracking.
Name |
Description | Default Value |
---|---|---|
attribution.disabled |
boolean . Whether disable the attribution tracking. |
false |
attribution.excludeReferrers |
string[] . Exclude the attribution tracking for the provided referrers string |
Including all referrers by default. |
attribution.initialEmptyValue |
string . Customize the initial empty value for attribution related user properties to any string value. |
EMPTY |
attribution.resetSessionOnNewCampaign |
boolean . Whether reset the sessionId on a new campaign. |
SDK won't create a new session for new campaign by default. |
pageViewTracking.trackOn |
attribution or () => boolean . attribution - Fire a page view event attribution information changes. undefined - Fire a page view event on page load or on history changes for single page application, default behavior. () => boolean - Fire a page view events based on a trackOn functions |
undefined |
pageViewTracking.trackHistoryChanges |
pathOnly or all or undefined . Use this option to subscribe to page view changes in a single page application like React.js. pathOnly - Compare the path only changes for page view tracking. all - Compare the full url changes for page view tracking. undefined - Default behavior. Page view changes in single page applications does not trigger a page view event. |
undefined |
Configure batching behavior¶
To support high performance environments, the SDK sends events in batches. Every event logged by track
method is queued in memory. Events are flushed in batch 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.
Note
For EU data residency, the project must be set up inside Amplitude EU. You must initialize the SDK with the API key from Amplitude EU.
amplitude.init(API_KEY, OPTIONAL_USER_ID, {
serverZone: 'EU',
});
Web attribution¶
With web attribution tracking, Amplitude supports automatically tracking the following attribution parameters:
- The 5 standard UTM parameters from the user's browser cookie or URL parameters
- The referring URL and domain
- 9 Click Identifiers
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:
Name |
Description |
---|---|
utm_source |
This identifies which website sent the traffic (for example, Google, Facebook) |
utm_medium |
This identifies a specific campaign used (for example, "summer_sale") |
utm_campaign |
This identifies a specific campaign used (for example, "summer_sale") |
utm_term |
This identifies paid search terms used (for example, product+analytics) |
utm_content |
This identifies what brought the user to the site and is commonly used for A/B testing (for example, "bannerlink", "textlink") |
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=bannerlink
Referrer parameters¶
Referrer is the URL of the page that linked to the destination page. Amplitude tracks the following parameters:
Name |
Description |
---|---|
referrer |
The last page the user was on (for example, https://amplitude.com/behavioral-analytics-platform?ref=nav ) |
referring_domain |
The domain that the user was last on (for example, https://amplitude.com ) |
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 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.
Name |
Description |
---|---|
GCLID |
Google Click Identifier from URL parameters |
FBCLID |
Facebook Click Identifier from URL parameters |
DCLID |
Google campaign manager Click Identifier |
GBRAID |
Google Click Identifier for iOS device from Web to App |
WBRAID |
Google Click Identifier for iOS device from App to Web |
KO_CLICK_ID |
Kochava Click Identifier from URL parameters |
MSCLKID |
Microsoft Click Identifier |
TTCLID |
TikTok Click Identifier |
TWCLID |
Twitter Click Identifier from URL parameter |
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
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
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 attriubtion.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 reset the session on a new campaign. 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
:
Name |
Description |
---|---|
all |
All pushes and pops from history send a page view. |
pathOnly |
Page Views are sent if the URL pathname changes. This prevents changes to the querystring or hash from sending events. |
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'
}
});
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.
- Add the Marketing Analytics Browser SDK to your project.
- Create an instance of the SDK.
- 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
}
});
Still have questions? Ask them in the Community.