Integrating Javascript tags onto your website - chuwy/snowplow-ci GitHub Wiki
HOME » SNOWPLOW SETUP GUIDE » Step 2: setup a Tracker » JavaScript Tracker » Integrating Javascript tags onto your website
This guide takes you through the process for integrating Snowplow's JavaScript Tracker into your website or web app.
The following guide covers the process for integrating Snowplow tracking tags directly onto your website. We recommend integrating Snowplow via a Tag Management solution. If you wish to integrate Snowplow tags using a tag management platform, we have provided separate guides for:
We recommend using the Snowplow asynchronous tags. Doing so means that the loading of the Snowplow tags will not cause site content to load more slowly, thereby providing a better experience for your users.
- Setting up Snowplow pageview tracking
- Tracking more than Pageviews. (Event tracking, ecommerce tracking, social tracking...)
- Next steps
In general, we recommend Snowplow users to install the asyncronous version of the Snowplow tags. These enable web pages to load faster, by only firing Snowplow tracking events after page load is complete.
To use sp.js in an 'async' manner, first add the following script into your website template's <head> section:
<!-- Snowplow starts plowing -->
<script type="text/javascript">
;(function(p,l,o,w,i,n,g){if(!p[i]){p.GlobalSnowplowNamespace=p.GlobalSnowplowNamespace||[];
p.GlobalSnowplowNamespace.push(i);p[i]=function(){(p[i].q=p[i].q||[]).push(arguments)
};p[i].q=p[i].q||[];n=l.createElement(o);g=l.getElementsByTagName(o)[0];n.async=1;
n.src=w;g.parentNode.insertBefore(n,g)}}(window,document,"script","//d1fc8wv8zag5ca.cloudfront.net/2.6.2/sp.js","snowplow"));
window.snowplow('newTracker', 'cf', '{{MY-COLLECTOR-URI}}', { // Initialise a tracker
appId: '{{MY-SITE-ID}}',
cookieDomain: '{{MY-COOKIE-DOMAIN}}'
});
window.snowplow('trackPageView');
</script>
<!-- Snowplow stops plowing -->Note: The above snippet references JavaScript tracker v2.6.2 (//d1fc8wv8zag5ca.cloudfront.net/2.6.2/sp.js). To ensure you are using the latest version, please, check what it currently is at GitHub and amend accordingly.
You need to set the collector endpoint in the header script: this ensures that any data generated by the JavaScript Tracker is sent to the Collector your setup as part of the previous stage in the setup process.
This is done during by passing in the Collector's URI when constructing a new tracker instance with 'newTracker'. For example, if you are using a [Cloudfront Collector](Setting up the Cloudfront Collector) with Cloudfront subdomain "d3rkrsqld9gmqf":
window.snowplow('newTracker', 'cf', 'd3rkrsqld9gmqf.cloudfront.net', { // Initialise a tracker
appId: '{{MY-SITE-ID}}',
cookieDomain: '{{MY-COOKIE-DOMAIN}}'
});
If you are using another Collector type, for example a Clojure Collector with URI "snowplow-coll.acme.com", just pass in that collector's URI:
window.snowplow('newTracker', 'mycljcoll', 'snowplow-coll.acme.com', { // Initialise a tracker
appId: '{{MY-SITE-ID}}',
cookieDomain: '{{MY-COOKIE-DOMAIN}}'
});
Setting the collector endpoint is essential for Snowplow to work. Setting the application ID and cookie domain are optional. For details on setting these, see the [JavaScript technical documentation guide] (Javascript-Tracker).
### 1.2 Synchronous integrationTo use snowplow.js in a 'sync' manner, first add the following script into your website template's <head> section:
<!-- Snowplow starts plowing -->
<script type="text/javascript">
var spSrc = ('https:' == document.location.protocol ? 'https' : 'http') + '://d1fc8wv8zag5ca.cloudfront.net/2.5.1/sp.js';
document.write(unescape("%3Cscript src='" + spSrc + "' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var snowplowTracker = Snowplow.getTrackerUri('{{MY-COLLECTOR-URI}}');
snowplowTracker.setAppId('{{MY-SITE-ID}}');
snowplowTracker.setCookieDomain('{{MY-COOKIE-DOMAIN}}');
snowplowTracker.trackPageView();
} catch ( err ) {}
</script>
<!-- Snowplow stops plowing -->We recommend to use synchronous only for debugging purposes, as there's a big chance that many events from users with slow/2G connection will be lost.
## 2. Tracking more than just page views: event tracking, ecommerce tracking etc.Snowplow has been built to track more than simply page views. We believe, as far as possible, that every event that can happen on a user journey should be captured in Snowplow, and that includes every in-page events that might not result in a new page load. (Which are the only events that are captured as by the page view tracking already implemented.) The JavaScript Tracker incorporates a number of functions to capture a wealth of events including:
- Custom structured events. A general purpose event tracking tag that can be used to track events like add-to-baskets, video-plays amongst others. It is modelled closely on Google's Event tracking
- Ecommerce transactions. Use this to track orders placed on your site
- [Page pings] (2-Specific-event-tracking-with-the-Javascript-tracker#wiki-pagepings). Use this to track how long visitors dwell on each page on your site, and how they scroll of pages over time.
Detailed documentation on how to capture the complete range of events possible with Snowplow can be found in the Javascript Tracker section of the [Technical Documentation] (snowplow-technical-documentation).
Note: once you have finished setting up the additional Snowplow events (as documented in the Technical Documentation section), we recommend returning to the setup guide to complete your Snowplow installation.
## 3. Next stepsOnce you have integrated Snowplow tracking tags on your site, you can [test that the tags fire] (testing the javascript tracker is firing).