1 General parameters for the Javascript tracker v1

---

This documentation is for an old version of this tracker!

🚧 The documentation for the latest version can be found on the Snowplow documentation site.

---

This page refers to version 1 of the Snowplow JavaScript Tracker

2. General parameters

• 2.1 Setting the endpoint
  • 2.1.1 setCollectorCf
  • 2.1.2 setCollectorUrl
• 2.2 Setting the application ID
  • 2.2.1 setAppId
• 2.3 Setting the cookie domain
  • 2.3.1 setCookieDomain
• 2.4 Setting the user ID
  • 2.4.1 setUserId
• 2.5 Setting the URL as a custom value
  • 2.5.1 setCustomUrl
• 2.6 User privacy
  • 2.6.1 respectDoNotTrack
• 2.7 User fingerprinting
  • 2.7.1 enableUserFingerprinting
  • 2.7.2 setUserFingerprintSeed

There are three "global parameters" that can be set for the JavaScript Tracker:

1. The collector endpoint
2. The application ID
3. The cookie domain

Of them, the collector endpoint is essential - Snowplow will not function if this is not set. The other two global parameters (application ID and cookie domain) are optional. We will discuss in which cases these should be set below.

When set, these are global parameters should be set as part of the Snowplow pageview tracking tags, before the actual trackPageView method is called e.g.

<!-- Snowplow starts plowing -->
<script type="text/javascript">
window._snaq = window._snaq || [];

window._snaq.push(['setCollectorCf', '{{MY-CLOUDFRONT-DOMAIN}}']);
window._snaq.push(['setAppId', '{{MY-SITE-ID}}']);
window._snaq.push(['setCookieDomain', '{{MY-COOKIE-DOMAIN}}'])
window._snaq.push(['trackPageView']);

(function() {
var sp = document.createElement('script'); sp.type = 'text/javascript'; sp.async = true; sp.defer = true;
sp.src = ('https:' == document.location.protocol ? 'https' : 'http') + '://cdn.jsdelivr.net/gh/snowplow/sp-js-assets@1/sp.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(sp, s);
})();
 </script>
<!-- Snowplow stops plowing -->

2.1 Setting the endpoint

Endpoint refers to the location of your collector: you need to point your JavaScript Tracker to your collector endpoint, to ensure that data generated by the Tracker is logged by the collector.

It is essential that the Tracker end point is set for data generated by the Tracker to pass successfully to the Snowplow collector.

If you are using a Cloudfront collector you can use setCollectorCf to set the endpoint. If you are using any other collector (e.g. the Clojure Collector or the Scala Stream Collector), then you should use setCollectorUrl.

2.1.1 Setting a Cloudfront endpoint using setCollectorCf

You can set the collector endpoint for the Cloudfront collector using:

window._snaq.push(['setCollectorCf', '{{CLOUDFRONT-SUBDOMAIN}}']);

So if your domain is d3rkrsqld9gmqf, you would include:

window._snaq.push(['setCollectorCf', 'd3rkrsqld9gmqf']);

in your Snowplow tag.

Back to top Back to JavaScript technical documentation contents

2.1.2 Setting a collector endpoint (e.g. for the Clojure collector) using setCollector URL

If you are running a different collector (not the Cloudfront collector) then you set the collector endpoint using:

window._snaq.push(['setCollectorUrl', '{{COLLECTOR-URL}}'])

E.g. if your collector endpoint is at 'my-company.c.snplow.com' then you would include:

window._snaq.push(['setCollectorUrl', 'my-company.c.snplow.com'])

in your Snowplow tags.

Back to top Back to JavaScript technical documentation contents

2.2 Setting the application ID

You can set different application IDs on different parts of your site. You can then distinguish events that occur on different applications by grouping results based on application_id.

2.2.1 Setting the application ID using setAppId

To set the application ID, use the setAppId method i.e.:

window._snaq.push(['setAppId', 'my_application_id_here']);

Back to top Back to JavaScript technical documentation contents

2.3 Setting the cookie domain

If your website spans multiple subdomains e.g.

• www.mysite.com
• blog.mysite.com
• application.mysite.com

You will want to track user behaviour across all those subdomains, rather than within each individually. As a result, it is important that the domain for your first party cookies is set to '.mysite.com' rather than 'www.mysite.com'. By doing so, any values that are stored on the cookie on one of subdomain will be accessible on all the others.

2.3.1 Setting the cookie domain using setCookieDomain

Snowplow will, as standard, set the cookie domain to the current domain. So if your visitor is on 'www.mysite.com', that will be the default domain the cookie is assigned to.

To assign the cookie to '.mysite.com' instead, execute:

window._snaq.push(['setCookieDomain', '.mysite.com']);

Back to top Back to JavaScript technical documentation contents

2.4 Setting the user ID

The JavaScript Tracker automatically sets a domain_userid based on a first party cookie.

There are many situations, however, when you will want to identify a specific user using an ID generated by one of your business systems. To do this, you use the setUserId method.

2.4.1 Setting the user ID using setUserId

To set the user ID, use the setUserId method i.e.:

window._snaq.push(['setUserId', 'joe.blogs@email.com']);

Typically, companies employ this method at points in the customer journey when the user identifies him / herself e.g. if he / she logs in.

Note: this will only set the user ID on further events fired while the user is on this page; if you want events on another page to record this user ID too, you must call setUserId on the other page as well.

Back to top Back to JavaScript technical documentation contents

2.5 Setting a custom URL

The Snowplow JavaScript Tracker automatically tracks the page URL on any event tracked.

However, in certain situations, you may want to override the actual URL with a custom value. (For example, this might be desirable if your CMS spits out particularly ugly URLs that are hard to unpick at analysis time.) In that case, you can override the default value using the setCustomUrl function.

2.5.1 Setting a custom URL using setCustomUrl

To set a custom URL, use the setCustomUrl method i.e.:

window._snaq.push(['setCustomUrl', 'http://mysite.com/checkout-page']);

2.6 User privacy

Most browsers offer a Do Not Track feature, allowing users to request not to be tracked by websites. The JavaScript Tracker gives you the option to respect that preference.

2.6.1 Respecting a user's privacy preferences using respectDoNotTrack

Use the respectDoNotTrack method like so:

window._snaq.push(['respectDoNotTrack', true]);

If a user's Do Not Track feature is enabled, this will prevent the JavaScript Tracker from setting cookies or sending events to a collector.

Back to top Back to JavaScript technical documentation contents

2.7 User fingerprinting

The Tracker generates a user fingerprint based on various browser features. This fingerprint is likely to be unique and so can be used to track anonymous users.

2.7.1 Turning off user fingerprinting using enableUserFingerprinting

User fingerprinting is turned on by default. To switch it off, use the enableUserFingerprinting method:

window._snaq.push(['enableUserFingerprinting', false]);

2.7.2 Setting the user fingerprint seed using setUserFingerprintSeed

You can change the hash seed used to generate the user fingerprint with the setUserFingerprintSeed method:

window._snaq.push(['setUserFingerprintSeed', 149257683]);

Back to top Back to JavaScript technical documentation contents