This is the official documentation for the Amplitude Analytics JavaScript SDK.
This is a maintenance SDK and will only receive bug fixes until deprecation. Upgrade to the latest Browser SDK 2.0 which supports plugins and more.
This SDK uses modern JavaScript features. For browser compatibility information, see the following links:
To ensure wider browser support and ES5 conformity, use Amplitude's TypeScript Browser SDK.
Install the Amplitude Analytics JavaScript SDK in your project.
Install the JavaScript SDK using a small snippet of code that you paste on your site to asynchronously load the SDK.
On every page that you want to install Amplitude analytics, paste the code snippet just before the </head>
tag, replacing AMPLITUDE_API_KEY
with your project's API key.
You can find your project's API Key in your project's Settings page.
1<script type="text/javascript"> 2(function(e,t){var n=e.amplitude||{_q:[],_iq:{}};var r=t.createElement("script") 3r.type="text/javascript"; 4r.integrity="sha384-5fhzC8Xw3m+x5cBag4AMKRdf900vw3AoaLty2vYfcKIX1iEsYRHZF4RLXIsu2o+F" 5r.crossOrigin="anonymous";r.async=true; 6r.src="https://cdn.amplitude.com/libs/amplitude-8.21.4-min.gz.js"; 7r.onload=function(){if(!e.amplitude.runQueuedFunctions){console.log( 8"[Amplitude] Error: could not load SDK")}};var s=t.getElementsByTagName("script" 9)[0];s.parentNode.insertBefore(r,s);function i(e,t){e.prototype[t]=function(){10this._q.push([t].concat(Array.prototype.slice.call(arguments,0)));return this}}11var o=function(){this._q=[];return this};var a=["add","append","clearAll",12"prepend","set","setOnce","unset","preInsert","postInsert","remove"];for(13var c=0;c<a.length;c++){i(o,a[c])}n.Identify=o;var l=function(){this._q=[];14return this};var u=["setProductId","setQuantity","setPrice","setRevenueType",15"setEventProperties"];for(var p=0;p<u.length;p++){i(l,u[p])}n.Revenue=l;var d=[16"init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut",17"setVersionName","setDomain","setDeviceId","enableTracking",18"setGlobalUserProperties","identify","clearUserProperties","setGroup",19"logRevenueV2","regenerateDeviceId","groupIdentify","onInit","onNewSessionStart"20,"logEventWithTimestamp","logEventWithGroups","setSessionId","resetSessionId",21"getDeviceId","getUserId","setMinTimeBetweenSessionsMillis",22"setEventUploadThreshold","setUseDynamicConfig","setServerZone","setServerUrl",23"sendEvents","setLibrary","setTransport"];function v(t){function e(e){t[e24]=function(){t._q.push([e].concat(Array.prototype.slice.call(arguments,0)))}}25for(var n=0;n<d.length;n++){e(d[n])}}v(n);n.getInstance=function(e){e=(26!e||e.length===0?"$default_instance":e).toLowerCase();if(27!Object.prototype.hasOwnProperty.call(n._iq,e)){n._iq[e]={_q:[]};v(n._iq[e])}28return n._iq[e]};e.amplitude=n})(window,document);29 30amplitude.getInstance().init(AMPLITUDE_API_KEY);31</script>
1npm install amplitude-js
1yarn add amplitude-js
You can also install the npm module and embed the SDK directly into your product.
After you've installed the SDK, import amplitude
into your project.
1import amplitude from 'amplitude-js';
1// initialize the client2var instance1 = amplitude.getInstance().init(AMPLITUDE_API_KEY);
1// send an event2const event = "Button Clicked";3amplitude.getInstance().logEvent(event);
The following functions make up the core of the Amplitude Analytics JavaScript SDK.
Before you can instrument, you must initialize the SDK using the API key for your Amplitude project.
Initialization creates a default instance, but you can create more instances using getInstance
with a string name.
1var instance1 = amplitude.getInstance().init("AMPLITUDE_API_KEY"); // initializes default instance of Amplitude client2var instance2 = amplitude.getInstance("instance-name").init("AMPLITUDE_API_KEY"); // initializes named instance of Amplitude client
Pass custom options in the init
method. See a list of options on GitHub.
1var options = {};2var instance = amplitude.getInstance("instance").init(AMPLITUDE_API_KEY, null, options); // initializes with the given options
Configuration options
Name
Description
Default Value
apiEndpoint
string
. Endpoint to send Amplitude event requests to.https://api.amplitude.com
batchEvents
boolean
. Whether batch send events. If true
, then events are batched together and uploaded only when the number of unsent events is greater than or equal to eventUploadThreshold or after eventUploadPeriodMillis milliseconds have passed since the first unsent event was logged.false
cookieExpiration
number
. The number of days after which the Amplitude cookie will expire. 12 months is for GDPR compliance.365
sameSiteCookie
string
. Sets the SameSite flag on the amplitude cookie. Decides cookie privacy policy.Lax
cookieForceUpgrade
boolean
. Forces pre-v6.0.0 instances to adopt post-v6.0.0 compat cookie formats.false
disableCookies
boolean
. Whether disable Amplitude cookies altogether.false
deferInitialization
boolean
. Whether defer initialization. If true
, disables the core functionality of the sdk, including saving a cookie and all logging, until explicitly enabled.false
deviceIdFromUrlParam
boolean
. If true
, then the SDK will parse Device ID values from the URL parameter amp_device_id if available. Device IDs defined in the configuration options during init will take priority over Device IDs from URL parameters.false
domain
string
. Set a custom domain for the Amplitude cookie. To include subdomains, add a preceding period, eg: .amplitude.com
.null
eventUploadPeriodMillis
number
. Amount of time in milliseconds that the SDK waits before uploading events if batchEvents is true.30 seconds
eventUploadThreshold
number
. Minimum number of events to batch together per request if batchEvents is true.30
forceHTTPs
boolean
. Whether force to upload toHTTPS endpoint. If true
, the events will always be uploaded to HTTPS endpoint. Otherwise, it will use the embedding site's protocol.true
includeFbclid
boolean
. If true
, captures the fbclid URL parameter as well as the user's initial_fbclid via a setOnce operation.false
includeGclid
boolean
. If true
, captures the gclid URL parameter as well as the user's initial_gclid via a setOnce operation.false
includeReferrer
boolean
. If true
, captures the referrer and referring_domain for each session, as well as the user's initial_referrer and initial_referring_domain via a setOnce operation.false
includeUtm
boolean
. If true
, finds UTM parameters in the query string or the _utmz cookie, parses, and includes them as user properties on all events uploaded. This also captures initial UTM parameters for each session via a setOnce operation.false
language
string
. Custom language to set.The language determined by the browser.
library
Object
. Values for the library version{ name: 'amplitude-js', version: packageJsonVersion }
logLevel
string
. 'DISABLE', 'ERROR', 'WARN', 'INFO'. Level of logs to be printed in the developer console.WARN
logAttributionCapturedEvent
boolean
. If true
, the SDK will log an Amplitude event anytime new attribution values are captured from the user. Note: These events count towards your event volume. Event name being logged: [Amplitude] Attribution Captured. Event Properties that can be logged: utm_source
, utm_medium
, utm_campaign
, utm_term
, utm_content
, referrer
, referring_domain
, gclid
, fbclid
.false
optOut
boolean
. Whether or not to disable tracking for the current user.false
onError
function
. Function to call on error.() => {}
onExitPage
function
. Function called when the user exits the browser. Useful logging on page exit.() => {}
platform
string
. Platform device is running on.Web
(browser, including mobile browsers).
savedMaxCount
number
. Maximum number of events to save in localStorage. If more events are logged while offline, then old events are removed.1000
saveEvents
boolean
. If true
, saves events to localStorage and removes them upon successful upload. Without saving events, events may be lost if the user navigates to another page before the events are uploaded.true
saveParamsReferrerOncePerSession
boolean
. If true
, then includeGclid, includeFbclid, includeReferrer, and includeUtm will only track their respective properties once per session. New values that come in during the middle of the user's session will be ignored. Set to false to always capture new values.true
secureCookie
boolean
. If true
, the amplitude cookie will be set with the Secure flag.false
sessionTimeout
number
. The time between logged events before a new session starts in milliseconds.30 minutes
storage
string
. Options are cookies
, localStorage
, sessionStorage
, or none
. Sets storage strategy. Will override disableCookies
option.Empty String
trackingOptions
Object
. Type of data associated with a user.Enable all tracking options by default. Please check here for more details.
transport
string
. http
or beacon
. Network transport mechanism used to send events.http
unsetParamsReferrerOnNewSession
boolean
. If false
, the existing referrer
and utm_parameter
values will be carried through each new session. If set to true
, the referrer
and utm_parameter
user properties, which include referrer
, referring_domain
, utm_source
, utm_medium
, utm_campaign
, utm_term
, and utm_content
, will be set to null
upon instantiating a new session. Note: This only works if includeReferrer
or includeUtm
is set to true
.false
unsentKey
string
. localStorage key that stores unsent events.amplitude_unsent
unsentIdentifyKey
string
. localStorage key that stores unsent identifies.amplitude_unsent_identify
uploadBatchSize
number
. The maximum number of events to send to the server per request.100
headers
Object
. Headers attached to an event(s) upload network request. Custom header properties are merged with this object.{ 'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8' }
serverZone
string
. US
or EU
. The server zone to send to, will adjust server url based on this config.US
useDynamicConfig
boolean
. To update api endpoint with serverZone change or not. For data residency, recommend to enable it unless using own proxy server.false
serverZoneBasedApi
boolean
. localStorage key that stores unsent events.false
sessionId
number
. The custom Session ID for the current session. *Note: This is not recommended unless you know what you are doing because the Session ID of a session is utilized for all session metrics in Amplitude.null
partnerId
number
. The partner id value.null
To support high-performance environments, the SDK sends events in batches. Every event logged by logEvent
method is queued in memory. Events are flushed in batches in background. You can customize batch behavior with eventUploadThreshold
and eventUploadPeriodMillis
. By default, the serverUrl will be https://api.amplitude.com
. This SDK doesn't support batch mode, the batch API endpoint.
1amplitude.getInstance().init(apiKey, null, {2 // Events queued in memory will flush when number of events exceed upload threshold3 // Default value is 304 eventUploadThreshold: 50,5 // Events queue will flush every certain milliseconds based on setting6 // Default value is 30000 milliseconds7 eventUploadPeriodMillis: 100000,8});
Beginning with version 8.9.0, you can configure the server zone to send data to Amplitude's EU server after initializing the client.
The server zone configuration supports dynamic configuration as well.
For earlier versions, you need to configure the apiEndpoint
property after initializing the client.
For EU data residency, you must initialize the SDK with the API key from Amplitude EU. Your project must be set up from inside Amplitude EU.
Version 8.9.0 and higherEarlier versions
1// No need to call setServerUrl for sending data to Amplitude's EU servers2amplitude.getInstance().init(euApiKey, null, {3 serverZone: 'EU',4 serverZoneBasedApi: true,5});
1amplitude.getInstance().init(euApiKey, null, {2apiEndpoint: 'https://api.eu.amplitude.com'3});
userID
Set userID
when initializing the client, or after initialization with the setUserId
method.
1var userId = "12345";2amplitude.getInstance().init(AMPLITUDE_API_KEY, userId); // initializes client with the given userId
1var userId = "12345";2amplitude.getInstance().setUserId(userId);
There is an optional startNewSession
parameter for setUserId
. Set it to true
to start a new user session.
Events represent user interactions with your app. For example, "Button Clicked" may be an action you want to track.
1const event = "Button Clicked";2amplitude.getInstance().logEvent(event);
Events can have properties that give context about the event. For example, "hover time" is a relevant property for the "Button Clicked" event.
1var event = "Button Clicked";2var eventProperties = {3 "hover time": "100ms"4};5amplitude.getInstance().logEvent(event, eventProperties);
Valid data types for event properties are string, array, object, boolean, and number. Object keys have a 1000 character limit.
Event property values can be arrays. You can query array event properties by any subset of the individual properties in the array.
1var event = "Button Clicked"; 2var eventProperties1 = { 3 "selectedColors": ['red', 'blue'] 4}; 5amplitude.getInstance().logEvent(event, eventProperties1); 6 7var eventProperties2 = { 8 "selectedColors": ['red', 'green'] 9};10amplitude.getInstance().logEvent(event, eventProperties2);
User properties help you understand your users at the time they performed some action within your app. For example, you can learn about their device details, their preferences, or language.
The Amplitude Identify object provides controls over setting user properties. First, create an Identify object instance, then call Identify methods on it, and then the client makes a call with the Identify object.
1new amplitude.Identify(); // does nothing, must call one of the following methods and pass to client2 3var identify = new amplitude.Identify();4amplitude.getInstance().identify(identify); // makes identify call to amplitude with the properties of the identify object
set
Set the value of a user property. You can also chain together several set
calls.
1var identify1 = new amplitude.Identify().set('key1', 'value1');2var identify2 = new amplitude.Identify().set('key2', 'value2').set('key3', 'value3');3amplitude.getInstance().identify(identify1);4amplitude.getInstance().identify(identify2);
setOnce
setOnce
sets the value of a user property one time. Subsequent calls using setOnce
are ignored.
1var identify = new amplitude.Identify().setOnce('key1', 'value1');2amplitude.getInstance().identify(identify);
add
Increment a user property by a number with add
. If the user property doesn't have a value set yet, it's initialized to 0
.
1var identify = new amplitude.Identify().add('value1', 10);2amplitude.getInstance().identify(identify);
You can use setUserProperties
as a shorthand to set multiple user properties at one time.
For example, set a user's city with this code:
1var userProperties = {2 city: "San Francisco"3};4amplitude.getInstance().setUserProperties(userProperties);
This method is a wrapper around Identify.set
and identify
.
User properties can be arrays. Directly set arrays or use append
to generate an array.
1var values = ['value1', 'value2'];2var identify = new amplitude.Identify().set('key1', values);3amplitude.getInstance().identify(identify);
prepend
and append
append
appends a value or values to a user property array.prepend
prepends a value or values to a user property array.If the user property doesn't have a value set yet, it's initialized to an empty list before adding the new values. If the user property has an existing value and it's not a list, it's converted into a list with the new value added.
Amplitude supports assigning users to groups and performing queries, such as Count by Distinct, on those groups. If at least one member of the group has performed the specific event, then the count includes the group.
For example, you want to group your users based on what organization they're in by using an 'orgId'. Joe is in 'orgId' '10', and Sue is in 'orgId' '15'. Sue and Joe both perform a certain event. You can query their organizations in the Event Segmentation Chart.
When setting groups, define a groupType
and groupName
. In the previous example, 'orgId' is the groupType
and '10' and '15' are the values for groupName
. Another example of a groupType
could be 'sport' with groupName
values like 'tennis' and 'baseball'.
Setting a group also sets the groupType:groupName
as a user property, and overwrites any existing groupName
value set for that user's groupType
, and the corresponding user property value. groupType
is a string, and groupName
can be either a string or an array of strings to indicate that a user is in multiple groups.
If Joe is in 'orgId' '10' and '16', then the groupName
would be '["10", "16"]'. Your code might look like this:
1amplitude.getInstance().setGroup('orgId', ["10","16"]);
You can also use logEventWithGroups
to set event-level groups. With event-level groups, the group designation applies only to the specific event being logged, and doesn't persist on the user unless explicitly
set with setGroup
.
1var eventProperties = {2 'key': 'value'3}4 5amplitude.getInstance().logEventWithGroups('initialize_game', eventProperties, {'sport': 'soccer'});
Use the Group Identify API to set or update the properties of particular groups. Keep these considerations in mind:
The groupIdentify
method accepts a group type string parameter and group name object parameter, and an Identify object that's applied to the group.
1var groupType = 'plan';2var groupName = 'enterprise';3var identify = new amplitude.Identify().set('key1', 'value1');4 5amplitude.getInstance().groupIdentify(groupType, groupName, identify);
You can supply an optional callback function as a fourth argument to groupIdentify
.
The best method of tracking revenue for a user is to use logRevenueV2()
in conjunction with the provided Revenue interface.
Revenue instances store each revenue transaction and let you define several special revenue properties used in Amplitude's Event Segmentation and Revenue LTV charts, such as revenueType
and productIdentifier
.
You can also add event properties to revenue events via the eventProperties
field. These Revenue instance objects are then passed into logRevenueV2
to send as revenue events to Amplitude.
This lets Amplitude to automatically display data relevant to revenue in the platform. You can use this to track both in-app and non-in-app purchases.
To track revenue from a user, call logRevenueV2()
each time a user generates revenue. Here is an example:
1var revenue = new amplitude.Revenue().setProductId('com.company.productId').setPrice(3.99).setQuantity(3);2amplitude.getInstance().logRevenueV2(revenue);
Calling logRevenueV2
generates a revenue event type:
You can't change the default names given to these client-side revenue events in the raw data but you do have the option to change the display name. To learn more about tracking revenue, see the documentation here.
Amplitude doesn't support currency conversion. Normalize all revenue data to your currency of choice before sending it to Amplitude.
Name | Description |
---|---|
productId |
Optional. String. An identifier for the product. Amplitude recommends something like the "Google Play Store product ID". Defaults to null . |
quantity |
Required. Integer. The quantity of products purchased. Note: revenue = quantity * price. Defaults to 1. |
price |
Required. Double. The price of the products purchased, and this can be negative. Note: revenue = quantity * price. Defaults to null . |
revenueType |
Optional, but required for revenue verification. String. The revenue type. For example, tax, refund, income. Defaults to null . |
eventProperties |
Optional. Object. An object of event properties to include in the revenue event. Defaults to null . |
Call setOptOut
to turn off logging for a given user:
1amplitude.getInstance().setOptOut(true);
While setOptOut
is enabled, events aren't saved or sent to the server. The opt out setting persists across page loads. You can re-enable logging by calling:
1amplitude.getInstance().setOptOut(false);
By default, the JavaScript SDK tracks some properties automatically. You can override this behavior by passing an object called trackingOptions
when initializing the SDK,
setting the appropriate options to false
.
Parameter | Default Value |
---|---|
city |
true |
country |
true |
carrier |
true |
device_manufacturer |
true |
device_model |
true |
dma |
true |
ip_address |
true |
language |
true |
os_name |
true |
os_version |
true |
platform |
true |
region |
true |
version_name |
true |
The trackingOptions
configurations prevent default properties from being tracked on new projects that have no existing data, not existing data. If you have a project with existing data that you would like to stop collecting the default properties for, contact the Support team at support.amplitude.com.
Existing data isn't deleted.
If your app has its login system that you want to track users with, you can call setUserId
at any time:
1amplitude.getInstance().setUserId('USER_ID');
You can also add the User ID as an argument to the init call.
1amplitude.getInstance().init(AMPLITUDE_API_KEY, 'USER_ID');
Don't assign users a user ID that could change, because each unique user ID represents a unique user in Amplitude. For more information see Track unique users in Amplitude in the Help Center.
Amplitude merges user data, so any events associated with a known userId
or deviceId
are linked the existing user.
If a user logs out, Amplitude can merge that user's logged-out events to the user's record. You can change this behavior and log those events to an anonymous user instead.
To log events to an anonymous user:
userId
to null.deviceId
.Events coming from the current user or device appear as a new user in Amplitude. Note: If you do this, you can't see that the two users were using the same device.
1amplitude.getInstance().setUserId(null); // not string 'null'2amplitude.getInstance().regenerateDeviceId();
Events triggered within 30 minutes of each other count towards the current session.
The time of the first event marks the start time of a session and the last event triggered marks the end time of a session.
You can change the session timeout window via the SDK configuration option field sessionTimeout
.
In the JavaScript SDK, you can use the helper method getSessionId
to get the value of the current sessionId
:
1const sessionId = amplitude.getInstance().getSessionId();
If you are using a domain proxy that requires custom HTTP request headers, configure them with options.headers
during initialization.
1amplitude.getInstance().init(AMPLITUDE_API_KEY, null, {2 headers: {3 'x-session-id': appToken,4 'Content-Type': 'application/json;charset=utf-8'5 }6});
If you want to log events to multiple Amplitude projects, then must have separate instances for each Amplitude project.
Each instance allows for independent apiKeys
, userIds
, deviceIds
, and settings.
You must assign a name to each Amplitude project and instance and use that name consistently when fetching that instance to call functions.
After you have chosen a name for that instance you can't change it.
An instance's data and settings are associated with its name, and you must use that instance name for all future versions of your project to maintain data continuity.
Instance names don't need be the names of your projects in the Amplitude platform, but they need to remain consistent throughout your code. Each instance must also be initialized with the correct apiKey
.
Instance names must be non-null and non-empty strings. Names are case insensitive, and you can fetch each instance name by calling.
Each new instance has its own apiKey
, userId
, deviceId
, and settings.
The following is an example of how to set up and log events to two separate projects:
1// existing project, existing settings, and existing API key 2amplitude.getInstance().init('12345', null, {batchEvents: true}); 3// new project, new API key 4amplitude.getInstance('new_project').init('67890', null, {includeReferrer: true}); 5 6// need to reconfigure new project 7amplitude.getInstance('new_project').setUserId('joe@gmail.com'); 8amplitude.getInstance('new_project').setUserProperties({'gender':'male'}); 9amplitude.getInstance('new_project').logEvent('Clicked');10 11var identify = new amplitude.Identify().add('karma', 1);12amplitude.getInstance().identify(identify);13amplitude.getInstance().logEvent('Viewed Home Page');
While Amplitude's JavaScript SDK doesn't ingest web attribution data by default, setting it up is simple. The SDK can automatically ingest this information if you enable attribution configuration options.
Amplitude supports automatically tracking the following through the SDK configuration options:
includeUtm
.includeReferrer
.includeGclid
.includeFbclid
.UTM parameters stand for Urchin Traffic Monitor parameters and are useful for analyzing the effectiveness of different ad campaigns and referring sites. UTM parameters are case sensitive so they're considered different values if the capitalization varies.
There are five different standard UTM parameters:
utm_source
: This identifies which website sent the traffic (for example: Google, Facebook).utm_medium
: This identifies the link type that was used (for example: banner, button, email).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: "banner-link", "text-link").Here is an example URL:
https://www.amplitude.com/?utm_source=newsletter&utm_campaign=product_analytics_playbook&utm_medium=email&utm_term=product%20analytics&utm_content=banner-link
In Amplitude, after you set the includeUtm
option to true, the JavaScript SDK automatically pulls UTM parameters from the referring URL and include them as user properties on all relevant events:
includeGclid
: Gclid (Google Click Identifier) is a globally unique tracking parameter used by Google. If used, Google appends a unique parameter (for example: "?gclid=734fsdf3"
) to URLs at runtime. By setting this to true, the SDK captures initial_gclid
and gclid
as user properties.includeFbclid
: Fbclid (Facebook Click Identifier) is a globally unique tracking parameter used by Facebook. If used, Facebook appends a unique parameter (for example: "?fbclid=392foih3"
) to URLs at runtime. By setting this to true
, the SDK captures initial_fblid
and fbclid
as user properties.includeUtm
: If true
, finds the standard UTM parameters from either the URL or the browser cookie and sets them as user properties. This sets utm_source
, utm_medium
, utm_campaign
, utm_term
, and utm_content
as well as initial_utm_source
, initial_utm_medium
, initial_utm_campaign
, initial_utm_term
, and initial_utm_content
as user properties for the user.
UTM parameters are captured once per session by default and occurs when the user loads your site and the Amplitude SDK for the first time.
You can disable the once per session restriction through the saveParamsReferrerOncePerSession
configuration option. When the SDK detects that it should start a new session,
it pulls the UTM parameters that are available at the time. Those UTM parameters are set as user properties which persists for all the user's events going forward.
However, initial UTM parameters are captured one time for each user via a setOnce
operation.If you want to track how users are getting to your website, then track the referrer (the referring site).
Amplitude supports tracking these fields automatically:
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, amplitude.com
).After you set the includeReferrer
option to true
, Amplitude captures the referrer
and referring_domain
for each session and set them as user properties on relevant events:
includeReferrer
: When true
, captures the referrer
and referring_domain
for each session as user properties as well as the initial_referrer
and initial_referring_domain
user properties one time for each user.
The referrer is the entire URL while the referring_domain
is the domain name from where the user came from.Initial referring information is captured one time for each user via a setOnce
operation.
Amplitude can capture the initial UTM parameters and referrer information for each user. The first-touch attribution values are set when a user's non-null UTM parameters are seen for the first time. These 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
Capture these parameters by setting the JavaScript SDK configuration options includeReferrer
, includeUtm
, includeFbclid
, and includeGclid
to true
.
Initial attribution information for users can change if they're merged with another user.
Amplitude captures where a user came from for each of their sessions by setting these user properties:
utm_source
utm_medium
utm_campaign
utm_term
utm_content
referrer
referring_domain
gclid
fbclid
TO use this, set the JavaScript SDK configuration options includeReferrer
, includeUtm
, includeFbclid
, and includeGclid
to true
.
By default, the SDK saves values only at the start of the session, so if a user triggers some flow that causes them to land on the site again with a different set of UTM parameters within the same session,
the second set isn't saved.
If you set saveParamsReferrerOncePerSession
to false
in your JavaScript SDK configuration, the SDK always captures new values from the user. This updates these user properties throughout a session if they change:
utm_source
utm_medium
utm_campaign
utm_term
utm_content
referrer
referring_domain
gclid
fbclid
Some customers also instrument these user properties as arrays to keep track of all the attribution parameters seen within the same session for a single user.
This is an advanced use case.
These events count towards your event quota.
logAttributionCapturedEvent
to true
in your JavaScript SDK configuration, the SDK logs an Amplitude event anytime new attribution values are captured from the user.
Event Name: [Amplitude] Attribution Captured
Event Properties:
utm_source
utm_medium
utm_campaign
utm_term
utm_content
referrer
referring_domain
gclid
fbclid
Amplitude's JavaScript SDK supports integration with Google Tag Manager. See the demo app on GitHub for instructions on how to set it up.
Debugging in a browser can help you identify problems related to your code's implementation, as well as potential issues within the SDKs you're using. Here's a basic guide on how to use the browser's built-in Developer Tools (DevTools) for debugging.
You can find JavaScript errors under Inspect > Console, which might have the details about the line of code and file that caused the problem. The console also allows you to execute JavaScript code in real time.
amplitude.init(API_KEY, 'USER_ID')
in the browser console, it indicates that your amplitude.init
call might not have been triggered in your codebase or you are not using the correct amplitude instance during initialization. Therefore, please check your implementation."The Amplitude Instrumentation Explorer is an extension available in the Google Chrome Web Store. The extension captures each Amplitude event you trigger and displays it in the extension popup. It's important to ensure that the event has been sent out successfully and to check the context in the event payload.
The following are common issues specific to Browser SDK.
Ad Blocker
might lead to event dropping. The following errors indicate that the tracking has been affected by Ad Blocker
. When loading via a script tag, an error may appear in the console/network tab while loading the SDK script. When loaded with npm package, there could be errors in the network tab when trying to send events to the server. The errors might vary depending on the browser.
We recommend using a proxy server to avoid this situation.
Here is the information SDK stored in the cookies. This means that client behavior, like disabling cookies or using a private browser/window/tab, will affect the persistence of these saved values in the cookies. So, if these values are not persistent or are not increasing by one, that could be the reason.
Cross-Origin Resource Sharing (CORS) is a security measure implemented by browsers to restrict how resources on a web page can be requested from a different domain. It might cause this issue if you used setServerURL
.
Access to fetch at 'xxx' from origin 'xxx' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
Cross-origin resource sharing (CORS) prevents a malicious site from reading another site's data without permission. The error message suggests that the server you're trying to access is not allowing your origin to access the requested resource. This is due to the lack of the Access-Control-Allow-Origin
header in the server's response.
Access-Control-Allow-Origin
header to the server's responses. This would allow your origin to make requests. The value of Access-Control-Allow-Origin
can be * to allow all origins, or it can be the specific URL of your web page.Access-Control-Allow-Origin
header to the response before sending it back to the web page.If you have set up an API proxy and run into configuration issues related to that on a platform you"ve selected, that"s no longer an SDK issue but an integration issue between your application and the service provider.
If you set the logger to "Debug" level, and see track calls in the developer console, the track()
method has been called. If you don't see the corresponding event in Amplitude, the Amplitude Instrumentation Explorer Chrome extension, or the network request tab of the browser, the event wasn't sent to Amplitude. Events are fired and placed in the SDK's internal queue upon a successful track()
call, but sometimes these queued events may not send successfully. This can happen when an in-progress HTTP request is cancelled. For example, if you close the browser or leave the page.
There are two ways to address this issue:
beacon
during initialization or set the transport to beacon
upon page exit. sendBeacon
doesn't work in this case because it sends events in the background, and doesn't return server responses like 4xx
or 5xx
. As a result, it doesn't retry on failure. sendBeacon
sends only scheduled requests in the background. For more information, see the sendBeacon section.await
keyword before the call.Beginning with version 8.9.0, you can configure your apps to use dynamic configuration. This feature finds the best server URL automatically based on app users' location.
To use, set useDynamicConfig
to true
.
apiEndPoint
API, leave dynamic configuration off.setServerZone
to set it to EU zone.1amplitude.getInstance().init(euApiKey, null, {2 useDynamicConfig: true,3});
COPPA control in Amplitude's other SDKs disables tracking for IDFA, IDFV, city, location data (location_lat
and location_lng
), and IP address.
There's no interface for COPPA control in the JavaScript SDK because it doesn't track location_lat
, location_lng
, IDFA or IDFV. Instead, you can disable tracking for city
and ip_address
with trackingOptions
.
1var trackingOptions = {2city: false,3ip_address: false,4};
Get a user's current device ID with the following code:
1var deviceId = amplitude.getInstance().getDeviceId() // existing device ID
Configure Amplitude by passing an object as the third argument to the init:
1amplitude.getInstance().init(AMPLITUDE_API_KEY, null, {2 // optional configuration options3 saveEvents: true,4 includeUtm: true,5 includeReferrer: true6})
On initialization, the SDK creates a cookie that begins with the prefix amp_
and ends with this first six digits of your API key.
For example, amplitude.getInstance().init("a2dbce0e18dfe5f8e74493843ff5c053")
would create a cookie with the key amp_a2dbce
.
The cookie tracks this metadata for the SDK:
Disable cookies created by the SDK with the disableCookies
option. When you disable cookies, the JavaScript SDK defaults to using localStorage
to store its data.
LocalStorage is a great alternative, but can't track cookies across domains.
Because access to localStorage
is restricted by subdomain, you can't track anonymous users across subdomains of your product (for example: www.amplitude.com
vs analytics.amplitude.com
).
The JavaScript SDK defaults to setting the SameSite option on its cookies to None
. This can be overridden with the sameSiteCookie
option.
Amplitude recommends using Lax
unless there are instances where you have third party sites that POST
forms to your site.
An HTTPOnly option isn't technologically possible for cookies created by the SDK. The cookie is set on the client side and is used as a client-side data store. An SDK cookie can't set the HTTPOnly flag.
Legacy cookies created by the SDK were larger than the newer, more compact cookies.
For users that have older cookies, the SDK only removes old cookies and starts using the new cookie format if the cookieForceUpgrade
option is set to true
.
If you use the SDK in multiple products, and track anonymous users across those products, you be sure to set this option on all those products.
Upgrading cookies is only recommended if you are running into problems with oversized cookies.
If you are using RequireJS to load your JavaScript files, then you can use it to load the Amplitude JavaScript SDK script directly instead of using the loading snippet. If you take this approach you lose one of the key advantages of the snippet that lets your app to start and use the Amplitude SDK without having to wait for Amplitude to fully download.
1<script src='scripts/require.js'></script> <!-- loading RequireJS -->2<script>3 require(['https://cdn.amplitude.com/libs/amplitude-6.2.0-min.umd.gz.js'], function(amplitude) {4 amplitude.getInstance().init(AMPLITUDE_API_KEY); // replace AMPLITUDE_API_KEY with your Amplitude API key.5 window.amplitude = amplitude; // You can bind the amplitude object to window if you want to use it directly.6 amplitude.getInstance().logEvent('Clicked Link A');7 });8 </script>
You can also define the path in your RequireJS configuration like this:
1<script src='scripts/require.js'></script> <!-- loading RequireJS --> 2<script> 3 requirejs.config({ 4 paths: { 5 'amplitude': 'https://cdn.amplitude.com/libs/amplitude-6.2.0-min.umd.gz.js' 6 } 7 }); 8 9 require(['amplitude'], function(amplitude) {10 amplitude.getInstance().init(AMPLITUDE_API_KEY); // replace AMPLITUDE_API_KEY with your Amplitude API key.11 window.amplitude = amplitude; // You can bind the amplitude object to window if you want to use it directly.12 amplitude.getInstance().logEvent('Clicked Link A');13 });14</script>15<script>16 require(['amplitude'], function(amplitude) {17 amplitude.getInstance().logEvent('Page loaded');18 });19</script>
You can track anonymous behavior across two different domains. Amplitude identifies anonymous users by their device IDs which must be passed between the domains. For example:
www.example.com
www.example.org
Users who start on Site 1 and then navigate to Site 2 must have the device ID generated from Site 1 passed as a parameter to Site 2. Site 2 then needs to initialize the SDK with the device ID.
The SDK can parse the URL parameter automatically if deviceIdFromUrlParam
is enabled.
amplitude.getInstance().options.deviceId
.www.example.com?amp_device_id=device_id_from_site_1
)amplitude.init(AMPLITUDE_API_KEY, null, {deviceIdFromUrlParam: true})
.Amplitude supports automatically tracking:
includeUtm
is set to true during initialization.includeReferrer
is set to true during initialization.gclid
(Google Click ID) from URL parameters when the configuration option includeGclid is set to true during initialization.If tracking is enabled, then the SDK sets the values as user properties (for example, referrer
or utm_source
) one time per session. This called last touch attribution.
The SDK also saves the initial values like initial_referrer
and initial_utm_source
using a setOnce
operation.
After these values are set, they never change. This is called first touch attribution.
saveParamsReferrerOncePerSession
By default, the SDK saves the values only at the start of the session. For example, if a user lands on your site with an initial set of UTM parameters and triggers some flow that causes them
to land on your site again with a different set of UTM parameters within the same Amplitude session, the second set isn't saved.
You can set the configuration option saveParamsReferrerOncePerSession
to false
to remove that restriction so that the SDK always captures new values from the user.
unsetParamsReferrerOnNewSession
By default, the SDK carries over existing UTM Parameters and Referrer values at the start of a new session. For example,
if a users session expires, the SDK maps the user's Referrer and UTM Parameters to existing values.
To reset those values to null upon instantiating a new session, set unsetParamsReferrerOnNewSession
to true
.
logEvent
, identify
, and redirect
You can pass a callback function to logEvent
and identify
, which gets called after receiving a response from the server.
This is useful if timing may cause an event to not be captured before the browser navigates away from a webpage.
Putting the navigation in a callback to the logEvent
method guarantees the event is captured before the navigation occurs. Here is a logEvent example:
1amplitude.getInstance().logEvent("EVENT_TYPE", null, callback_function);
Here is an identify example:
1var identify = new amplitude.Identify().set('key', 'value');2amplitude.getInstance().identify(identify, callback_function);
The status and response body from the server are passed to the callback function, which you might find useful. Here is an example of a callback function which redirects the browser to another site after a response:
1var callback_function = function(status, response) {2 if (status === 200 && response === 'success') {3 // do something here4 }5 window.location.replace('URL_OF_OTHER_SITE');6};
You can also use this to track outbound links to your website. For example, you would have a link like this:
1<a href="javascript:trackClickLinkA();">Link A</a>
Then, you would define a function that's called when the link is clicked like this:
1var trackClickLinkA = function() {2 amplitude.getInstance().logEvent('Clicked Link A', null, function() {3 window.location='LINK_A_URL';4 });5};
In the case that optOut
is true
, then no event is logged but the callback is called.
In the case that batchEvents
is true
, if the batch requirements eventUploadThreshold
and eventUploadPeriodMillis
aren't met when logEvent
is called, then no request is sent but the callback is still called.
In these cases, the callback is called with an input status of 0 and a response of 'No request sent'.
You can pass a second callback to logEvent
and identify that are called if the network request for the event fails.
This is useful to detect if a user is using an ad blocker, or if there's an error from the Amplitude server due to an issue with the event format.
You can use the error callback together with the success callback like this:
1var successCallback = function() {2 console.log('the event was logged successfully');3}4 5var errorCallback = function() {6 console.log('there was an error logging the event')7};8 9amplitude.getInstance().logEvent('event', null, successCallback, errorCallback);
init
callbacksYou can also pass a callback function to init, which is called after the SDK finishes its asynchronous loading. The instance is passed as an argument to the callback:
1amplitude.getInstance().init(AMPLITUDE_API_KEY, 'USER_ID', null, function(instance) {2 console.log(instance.options.deviceId); // access Amplitude's deviceId after initialization3});
In SDK version 8.5.0 and higher, the SDK can send events using the browser's built-in navigator.sendBeacon API. Unlike standard network requests, sendBeacon sends events in the background, even if the user closes the browser or leaves the page.
Because sendBeacon
sends events in the background, events dispatched from sendBeacon
don't return a server response and can't be retried when they encounter failures like 4xx or 5xx errors. You can address these retry issues by sending one event/request, but this could increase the network load and the likelihood of throttling.
To send an event using sendBeacon, set the transport SDK option to 'beacon' in one of two ways
1// set transport to 'beacon' when initializing an event 2amplitude.getInstance().init(AMPLITUDE_API_KEY, 'USER_ID', {transport: 'beacon'}); 3 4// set transport to 'beacon' after initialization 5amplitude.getInstance().setTransport('beacon'); 6 7// this event will be sent using navigator.sendBeacon 8amplitude.getInstance().logEvent('send event with beacon'); 9 10// set transport back to the default 'http' value11amplitude.getInstance().setTransport('http');12 13// this event will be sent using the standard xhr mechanism14amplitude.getInstance().logEvent('send event with http');
The JavaScript SDK provides a convenient callback function that's called only when the user exits the page. It automatically switches the transport to 'beacon' for any logs sent in the callback. This callback is called onExitPage
and is passed into the SDK on initialization, like so:
1var exitCallback = function {2 amplitude.getInstance().logEvent('Logging a final event as user exits via sendBeacon');3};4 5amplitude.getInstance().init(AMPLITUDE_API_KEY, 'USER_ID', { onExitPage: exitCallback });
The SDK initializes the device ID in the following order, with the device ID being set to the first valid value encountered:
configuration.deviceIdFromUrlParam
is true. Refer to cross domain tracking for more detailsA device ID changes in many scenarios:
Amplitude Analytics SDKs share an identity store with Experiment SDKs
setDeviceId
also updates the identity store to propagate new user info to experiment SDK and trigger a fetch if device ID has changed.
setDeviceId()
is called explicitlyamp_device_id
when deviceIdFromUrlParam
is enabledYou can assign a new device ID using setDeviceId()
. When setting a custom device ID, make sure the value is sufficiently unique. Amplitude recommends using a UUID.
By default, the device ID is randomly generated base64 ID. You can define a custom device ID by setting it as a configuration option or by calling setDeviceId
.
1amplitude.getInstance().setDeviceId('DEVICE_ID');
You can retrieve the device ID that Amplitude uses with Amplitude.getInstance().getDeviceId()
or Amplitude.getInstance('YOUR-INSTANCE-NAME').getDeviceId()
if you defined a custom instance name. This method can return null
if a deviceId
hasn't been generated yet.
1const deviceId = amplitude.getInstance().getDeviceId();
Sometimes you have more than one Amplitude Javascript SDK instance setup and want to share the device ID across instances.
1// Initialize an instance with default configuration 2// Device Id of this instance is created by default 3var instanceDev = amplitude.getInstance("amplitude-dev"); 4instanceDev.init("API-KEY-1"); 5 6// Initialize another instance with a different API key 7// And pass the deviceId from the previous instance to the configuration 8var instanceProd = amplitude.getInstance("amplitude-prod"); 9instanceProd.init("API-KEY-2", undefined, {10 deviceId: instanceDev.getDeviceId()11});
1var instanceDev = amplitude.getInstance("amplitude-dev");2instanceDev.init("API-KEY-1");3 4var instanceProd = amplitude.getInstance("amplitude-prod");5instanceProd.init("API-KEY-2");6 7// Before the line blow, the device Ids of the two instances are different8instanceProd.setDeviceId(instanceDev.getDeviceId());
amp_device_id
. Refer to cross domain tracking for more details.If your web app configures the strict Content Security Policy (CSP) for security concerns, adjust the policy to whitelist the Amplitude domains:
https://*.amplitude.com
to script-src
.https://*.amplitude.com
to connect-src
.Thanks for your feedback!
September 17th, 2024
Need help? Contact Support
Visit Amplitude.com
Have a look at the Amplitude Blog
Learn more at Amplitude Academy
© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.