How to use Snowplow JS tracker

The Snowplow Javascript tracker allows us to collect engagement events across various University of Iowa web properties. These events are emitted from the javascript tracker to our event pipeline where the events are stored and analyzed.

Breaking changes when upgrading from v2 to v3.

There are breaking changes when making the move from v2 to v3 of the Javascript tracker. Please see Migrating from v2 to v3 for more info.

Setup

The library first needs to be loaded and configured. Place the following snippet early in your 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","//radar-cdn.its.uiowa.edu/sp-static-js/3.5.0/radar-tracker.js","snowplow"));

Configuration

The library then needs to be configured so the tracker knows how to emit events to the collectors.

window.snowplow('newTracker', 'sp', 'radar-collector.its.uiowa.edu', {
    appId: 'edu.uiowa.yoursite',
    cookieDomain: '.uiowa.edu',
    respectDoNotTrack: true,
    cookieSameSite: 'Lax',
    eventMethod: 'post',
    postPath: '/uiowa/utp1',
    contexts: {
        webPage: true
    }
});

Explanations of the sample key/value sent to the tracker. For a list of all the parameters, see Initialization options.

appId:
This is used to identify your tracker integration in the data. This should be changed to a unique value for your site/app.
cookieDomain:
The domain for which the tracking cookie should be set. Leave at .uiowa.edu.
respectDoNotTrack:
Boolean if the browser's do not track setting should be respected. Leave at true.
cookieSameSite:
The SameSite setting to use when setting cookies. Use Lax.
eventMethod:
The HTTP method to use when sending event payloads. Set to post.
postPath:
Path on the collector to send the request. Leave at /uiowa/utp1.
contexts:
Object of which contexts should be included in the event data. The webPage context is enabled by default in v3 of the tracker. Additional contexts that can be sent are: session, performanceTiming, gaCookies, clientHints, geolocation, and enableGeolocationContext. See Initialization options for more information on what those contexts send.

Usage:

If you have authenticated users you would need to pass along the UserId of the user so their identity can be stitched together. The UserId should be a SHA hash of a user's HawkID, UniversityId, @uiowa.edu email address, or private email address.

window.snowplow('setUserId', '{{userHash}}');

After configuration, you'll then need to emit events. To emit a pageView event you would inform the tracker to emit that event.

window.snowplow('trackPageView');

If you wanted to track activity on a page you would send a different event.

window.snowplow('enableActivityTracking', { minimumVisitLength: 15, heartbeatDelay: 15 });

v3 Upgrade Breaking Changes: The parameters passed to for enableActivityTracking have changed from v2.

References: