Important Note:
This article has been moved to our Developer Center, and will no longer be updated on this site. Here is the newest version of our Web Attribution Guide.
While Amplitude’s Javascript SDK does not collect web attribution data by default, setting it up is simple. The SDK can automatically collect this information if certain attribution configuration options are enabled.
Amplitude supports automatically tracking the following through the SDK configuration options:
- The 5 standard UTM parameters from the user's browser cookie or URL parameters by using
includeUtm
. - The referring URL and domain from
includeReferrer
. - Google Click Identifier from URL parameters through
includeGclid
.
Table of Contents
- Track UTM Parameters
- Track Referrers
- First-Touch Attribution
- Last-Touch Attribution
- Multi-Touch Attribution
Track UTM Parameters
UTM parameters stand for Urchin Traffic Monitor parameters and are useful for analyzing the effectiveness of different ad campaigns and referring sites. Note that UTM parameters are case sensitive so they will turn out to be different values if the capitalization varies.
There are five different standard UTM parameters:
- utm_source: This identifies which website sent the traffic (e.g. Google, Facebook).
- utm_medium: This identifies what type of link was used (e.g. banner, button, email).
- utm_campaign: This identifies a specific campaign used (e.g. summer_sale).
- utm_term: This identifies paid search terms used (e.g. product+analytics).
- utm_content: This identifies what brought the user to the site and is commonly used for A/B testing (e.g. bannerlink, textlink).
Here is an example URL where the values in purple are the parameters and the values in red would be your own:
https://www.amplitude.com/?utm_source=newsletter&utm_campaign=product_analytics_playbook&utm_medium=email&utm_term=product%20analytics&utm_content=bannerlink
Enabling via SDK
In Amplitude, once you set the includeUtm
option to true
, the JavaScript SDK will automatically pull UTM parameters from the referring URL and include them as user properties on all of the relevant events:
- includeGclid: Gclid (Google Click Identifier) is a globally unique tracking parameter used by Google. If utilized, Google will append a unique parameter (e.g. "?gclid=734fsdf3") to URLs at runtime. By setting this to
true
, the SDK will capture 'initial_glid' and 'gclid' 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 will set '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 will pull the UTM parameters that are available at the time. Those UTM parameters will be set as user properties which will persist for all of the user's events going forward. However, initial UTM parameters are captured only once for each user via a setOnce
operation. See the Javascript SDK Configuration Options for reference.
Track Referrers
If you want to track how users are getting to your website, then all you need to do is track the referrer (the referring site).
Here are the fields Amplitude supports tracking automatically:
- referrer: The last page the user was on (e.g. https://amplitude.com/behavioral-analytics-platform?ref=nav).
- referring_domain: The domain that the user was last on (e.g. amplitude.com).
Enabling via SDK
Once you set the includeReferrer
option to true
, Amplitude will capture the referrer
and referring_domain
for each session and set them as user properties on all of the relevant events:
- includeReferrer: If
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 once for each user. The referrer is the entire URL while the referring_domain is only the domain name from where the user came from.
Initial referring information is captured only once for each user via a setOnce
operation. See the Javascript SDK Configuration Options for reference.
First-Touch Attribution
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. The following user properties are set once:
- initial_utm_source
- initial_utm_medium
- initial_utm_campaign
- initial_utm_term
- initial_utm_content
- initial_referrer
- initial_referring_domain
- initial_gclid
This is done by setting the JavaScript SDK configuration options includeReferrer
, includeUtm
, and includeGclid
to true
.
Note: Initial attribution information for users can change if there are merged users.
Last-Touch Attribution
In addition to first-touch attribution, Amplitude will capture where a user came from for each of their sessions. This is accomplished by setting the following user properties:
- utm_source
- utm_medium
- utm_campaign
- utm_term
- utm_content
- referrer
- referring_domain
- gclid
This is done by setting the JavaScript SDK configuration options includeReferrer
, includeUtm
, and includeGclid
to true
. By default, the SDK will only save values 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, that second set will not be saved.
Multi-Touch Attribution
If you set saveParamsReferrerOncePerSession
to false
in your JavaScript SDK configuration, the SDK will always capture any new values from the user. This will update the following user properties throughout a session if they change:
- utm_source
- utm_medium
- utm_campaign
- utm_term
- utm_content
- referrer
- referring_domain
- gclid
Some customers also instrument these user properties as arrays in order to keep track of all the attribution parameters seen within the same session for a single user.