Snowplow JavaScript Tracker 2.1.1 released with new events

We are delighted to announce the release of version 2.1.1 of the Snowplow JavaScript Tracker! This release contains a number of new features, most prominently several new unstructured events and a context for recording the browser’s PerformanceTiming.

This blog post will cover the following topics:

1. New events
2. Page performance context
3. Link content
4. Tracker core integration
5. Custom callbacks
6. forceSecureTracker
7. Outbound queue
8. New example page
9. Other improvements
10. Upgrading
11. Getting help

1. New events

1.1 Automatic form tracking

Enable automatic form tracking using the enableFormTracking method:

snowplow('enableFormTracking'<span class="p">);

Whenever a user changes the value of a field in a form, the Tracker will fire a change_form unstructured event capturing the name, type, and CSS classes of the changed element, the ID of the parent form, and the new value of the field.

Whenever a user submits a form, the Tracker will fire a submit_form event. This event captures the ID of the parent form and the names, types, and final values of all input, select, and textarea elements in the form.

When you call the method, it will only attach event listeners to existing forms, so you should call it again whenever you create a new form element. (This is safe – the Tracker will not attach more than one event listener to an element.)

1.2 add_to_cart and remove_from_cart

Use the new trackAddToCart and trackRemoveFromCart methods to track add_to_cart and remove_from_cart events. The signatures of the methods are identical:

trackRemoveFromCart(sku, name, category, unitPrice, quantity, currency, context<span class="p">);

Use them like this:

snowplow('trackAddToCart', 'item-000303', 'small waistcoat', 'clothing', 79.99, 2, 'USD'<span class="p">);

1.3 social_interaction

The trackSocialInteraction method lets you track social_interaction events on you site. This is its signature:

trackSocialInteraction(action, network, target, context<span class="p">);

An example:

snowplow('trackSocialInteraction', 'like', 'Facebook', 'blog post 0012'<span class="p">);

1.4 site_search

The new site_search event describes a user performing a search on a website. It can capture the search terms and search filters used, the number of results found, and the number of results displayed on the first page.

This is the signature of the corresponding method:

trackSiteSearch(terms, filters, totalResults, pageResults, context<span class="p">);

And an example of trackSiteSearch in action:

snowplow('trackSiteSearch', ['event', 'streams'], { 'category': 'books', 'safeSearch': true }, 10, 8<span class="p">);

The filters parameter is a dictionary whose values can be strings or booleans.

2. Page performance context

The trackPageView method now accepts an additional boolean parameter named “performanceTracking”:

trackPageView(customTitle, performanceTracking, context<span class="p">);

If you set this parameter to true, a PerformanceTiming context will be added to the page view event. This context will contain all the data found in the window.performance.timing variable, and so can be used to calculate how long the page took to load.

3. Link content

The link_click event has been updated to include an optional content field. This will be populated with the innerHTML property of the link. The enableLinkClickTracking now has a “trackContent” parameter which you must set to true to capture the innerHTML of clicked links:

enableLinkClickTracking(criterion, pseudoClicks, trackContent, context<span class="p">);

The trackLinkClick method, which is used to track individual clicks manually, now accepts an additional string parameter named “content”:

trackLinkClick(targetUrl, elementId, elementClasses, elementTarget, elementContent, context<span class="p">);

4. Tracker core integration

The Snowplow JavaScript Tracker Core was designed to contain the functionality common to both the client-side JavaScript Tracker and the Node.js Tracker.

This release integrates the core into the client-side Tracker. As a consequence, the random 6-digit “transaction ID” attached to all events has been replaced by a unique type 4 UUID, which will serve as the event_id for this event. This makes the false positive rate for detecting duplicate events negligible.

5. Custom callbacks

You can now specify callback functions which will only be called when sp.js has been loaded and initialized:

function snowplowCallback() { console.log("Snowplow has loaded"<span class="p">); } snowplow(snowplowCallback<span class="p">);

6. forceSecureTracker

By default, events are sent to a collector using the same protocol (“http” or “https”) as the current page. Huge thanks to community member @kujo4pmZ for contributing the option to force the tracker to send all events over https! Just add a forceSecureTracker field when creating a tracker:

 window.snowplow('newTracker', 'cf', 'd3rkrsqld9gmqf.cloudfront.net', { // Initialise a tracker appId: 'CFe23a', platform: 'mob', forceSecureTracker: true // Requests will be made over https <span class="p">});

7. Outbound queue

Previous versions of the tracker had a pageUnloadTimer which you could use to set a pause between an event being created and the page unloading, to give the tracker time to fire the event. Version 2.1.1 makes the timeout more intelligent: once all queued events have been sent, the page will unload, even if the pageUnloadTimer has not yet expired.

8. New example page

The new async-large.html file shows how the Snowplow JavaScript Tracker works even if two people are independently loading and using it on the same page. It also provides examples of all the new unstructured events.

9. Other improvements

We have also:

• Moved the context field to the end of the querystring in case it gets truncated #204
• Improved the efficiency of link click tracking #254
• Extracted link tracking functionality into its own file #266
• Made the regular expression used to match IP addresses more strict #267
• Renamed the “dist” directory to “deploy” #216
• Improved the CodeClimate rating for the project #150
• Added further Intern unit tests #76
• Added a section to the README for contributors on getting the Vagrant environment set up #169

Finally, we thank Kevin Simper (@kevinsimper on GitHub) for his contribution preventing the localStorage queue of events from being incorrectly parsed.

10. Upgrading

10.1 JavaScript upgrade

The new minified and gzipped JavaScript is available at

http(s)://d1fc8wv8zag5ca.cloudfront.net/2.1.1/sp.js`

Note that this version introduces BREAKING changes to the trackPageView, enableLinkClickTracking, and trackLinkClick methods, all of which now have an additional penultimate parameter.

The deprecated legacy method trackImpression has been removed entirely; use trackAdImpression instead.

10.2 Redshift upgrade

If you are using Amazon Redshift, the new event types and performance context will require you to deploy new tables into your Redshift cluster.

For instructions on this, please see today’s Snowplow 0.9.10 release blog post.

11. Getting help

We have published full documentation for version 2.1.1.

If you have any suggestions for new features or need help getting set up, please get in touch. And raise an issue if you spot a bug!