Snowplow JavaScript Tracker 2.12.0 released

We are pleased to announce a new release of the Snowplow JavaScript Tracker. Version 2.12.0 introduces a brand new test suite powered by Snowplow Micro, giving us even more confidence as we continue to release updates to the Snowplow JavaScript Tracker and serving as an example of how Snowplow Micro can be integrated into a testing environment.

NB. This release continues with the change we introduced with v2.11.0 to how assets are hosted – rather than hosting the tracker on CloudFront, we now publish the asset to the GitHub release. Users who have previously relied on the CloudFront hosted asset must host the tracker on their own CDN, as is recommended practice. More detail can be found in our v2.11.0 release post.

Read on below the fold for:

1. New test suite powered by Snowplow Micro
2. Local Storage improvements
3. Updates and bug fixes
4. Upgrading
5. Documentation and help

1. New test suite powered by Snowplow Micro

This release introduces a new test suite into the Snowplow JavaScript Tracker which is powered by Snowplow Micro. Failing tests will automatically fail a build, preventing builds of the JavaScript Tracker from being published if they do not meet the requirements.

Snowplow Micro is a very small Snowplow Pipeline which can be initialised before running tests and then used to validate that data collection has occurred correctly. You can read more about Snowplow Micro in our earlier blog post.

In version 2.12.0 we have leveraged the capabilities of Snowplow Micro to build our own test suite which allows us to verify that the latest release of the Snowplow JavaScript Tracker is behaving as we expect. This gives us increased confidence in future releases of the Snowplow JavaScript Tracker.

Not only that, as we recommend using Snowplow Micro to build your own test suite, this release is a an example of how to include Snowplow Micro as one part of your testing strategy. The code changes that power our new test suite can be found here and will hopefully prove to be inspiration for your own Snowplow Micro powered test suite!

2. Local Storage improvements

In this release we also focused on ensuring our use of Local Storage is robust and as reliable as our cookie storage strategy. With that in mind, we have fixed two issues that have affected use of Local Storage.

1. When using the localStorage option of stateStorageStrategy, any state that was stored had no expiration time. Unlike Cookie storage which have expiry dates built in, Local Storage has no such mechanism. This effected functionality that incremented session counters, as the stored session id never expired when using Local Storage. This has now been solved by implementing expiration functionality on our local storage entries (Github #718). You can read more about the stateStorageStrategy options in our docs

2. We also fixed an issue in the local storage queue that the Snowplow JavaScript Tracker utilises to cache events before they are sent to the collector in a batch or to be queued if the event fails to send (for example, due to connectivity issues). Before this release, there was no upper limit on the size of the queue and this could impact the performance of the web application if it also relies on Local Storage. Most browsers only allow 5MB of Local Storage per site, so allowing control of limiting the Snowplow JavaScript Tracker use of local storage allows web developers to better decide how they wish to utilise their Local Storage limits (Github #764).

   NB. In the event the queue becomes full (due to connectivity issues or ad blockers blocking requests) events will be dropped. This is a change in behaviour from previous releases, which would have only dropped events when Local Storage was full for a site, however we expect with the default value of 1000 that dropped events are unlikely to occur.

The default limit is set to 1000 events in the queue, but it can be configured with the maxLocalStorageQueueSize argument when initialising the tracker. This functionality can be disabled by setting the maxLocalStorageQueueSize to 0, however this is not recommended if the site containing the Snowplow JavaScript Tracker also relies on Local Storage.

It can be changed at initialisation as follows:

snowplow("newTracker", "sp", "<collector-url>", { appId: "<app-id>", eventMethod: "post", maxLocalStorageQueueSize: 500, contexts: { webPage: true, performanceTiming: true } <span class="p">});

3. Updates and bug fixes

A big thank you to our community for the following contributions:

• @jethron: Fix OptimizelyX context collecting (#730)
• @miike: Core: Add function to allow setting Useragent (#744)
• @max-tgam: Fix dynamic context callbacks sometimes returning null (#743)

Other updates and bugfixes include:

• Update packages and test harness (#756)
• Fix osx+safari testing setup issues (#760)

4. Upgrading

The tracker is available as a published asset in the 2.12.0 Github release:

To upgrade, host the
sp.js asset in a CDN, and call the tracker from there.

There are no breaking API changes introduced with this release.

5. Documentation and help

Check out the JavaScript Tracker’s documentation:

• The setup guide
• The full API documentation

The v2.12.0 release page on GitHub has the full list of changes made in this version.

Finally, if you run into any issues or have any questions, please raise an issue or get in touch with us via our Discourse forums.