Tracker setup

JavaScript (tag)

There are two distributions of the JavaScript Tracker:

• sp.js is fully featured and is bundled with the majority of the available plugins.
• sp.lite.js is a smaller distribution with no bundled plugins. Included is Page View, Self Describing and Structured Event tracking as well as Activity Tracking and Anonymous Tracking. All other features can be loaded as separate plugins.

Use the following tag to your page to load sp.js:

<script type="text/javascript" async=1>
;(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","{{URL to sp.js}}","snowplow"));
</script>

Note: We recommend self hosting sp.js by following our Self hosting snowplow JS guides here. The latest versions are currently available at GitHub.

We also recommend renaming sp.js as this file name is commonly blocked by adblockers. Renaming to a random string will help ensure the JavaScript Tracker is loaded as expected.

Important note regarding testing: If the URL to sp.js is protocol-relative i.e. beginning with // when fetching sp.js. It will work if the your web page is using the “http” or “https” protocol. But if you are testing locally and loading your page from your filesystem using the “file” protocol (so its URI looks something like “file:///home/joe/snowplow_test.html”), the protocol-relative URL will also use that protocol, preventing the script from loading. To avoid this, change the URL to "http://.../sp.js" when testing locally.

As well as loading the JavaScript Tracker, this tag creates a global function called “snowplow” which you use to access the Tracker. You can replace the string “snowplow” with the function name of your choice. This is encouraged: if there are two JavaScript trackers on the same page, there won’t be any conflict between them as long as they have chosen different function names.

note

The rest of the documentation will assume that the function is called “snowplow”.

Once the tracker is loaded via the tag, you can move on to initializing the tracker.

Browser (npm)

Getting started with sending events using the Browser Tracker will be familiar for anyone who is used to installing npm packages into their web apps and is designed to work with frameworks such as React, Angular and Vue.

• Install the @snowplow/browser-tracker package using your preferred package manager

  • npm install @snowplow/browser-tracker
  • yarn add @snowplow/browser-tracker
  • pnpm add @snowplow/browser-tracker

• You can then import this library into your application

import { newTracker, trackPageView } from '@snowplow/browser-tracker';

• Configure an instance of the tracker by calling newTracker(...) with your desired properties. This will create a module level instance of your tracker. You don't need to keep a reference to it.

newTracker('sp1', '{{collector_url}}', { 
  appId: 'my-app-id', 
  plugins: [ ],
});

• Then you can use the track methods to send some events. You can send a Page View event to all initialised trackers with just:

trackPageView();

📄️ Initialization and configuration

Tracker initialization is started by calling the "newTracker" function and takes three arguments:

🗃️ Google Tag Manager

3 items

🗃️ Hosting the JavaScript tracker

4 items

📄️ Managing multiple trackers

You can have more than one tracker instance running on the same page at once. This may be useful if you want to log events to different collectors. By default, any Snowplow method you call will be executed by every tracker you have created so far.

📄️ Snowplow Plugin for getanalytics.io

The Snowplow JavaScript tracker can now be deployed directly into your web and node applications using the analytics and @analytics/snowplow NPM packages.