Snowplow NodeJS Tracker 0.4.0 released

We are pleased to announce a new release of the Snowplow NodeJS Tracker.

Version 0.4.0 significantly improves the developer experience through various updates. It also adds support for the dvce_sent_tstamp as well as the setting of the domain_userid and the network_userid (Snowplow’s client- and server-side cookie IDs). Finally, it switches the emitter from ‘request’ to ‘got’ alongside a bugfix. All of these updates mean there are two breaking API changes:

• The emitter has been replaced with the gotEmitter, which continues to offer the same functionality but also includes a number of new features.
• If you are using trackEcommerceTransaction and passing in an array of items, you should now switch to using trackEcommerceTransactionWithItems.

Read on below for more detail on:

1. Improving the developer experience
2. Adding the domain_userid and the network_userid
3. Support for the dvce_sent_tstamp
4. Switching to the got Emitter
5. Breaking changes
6. Bug fixes
7. Installation and upgrading
8. Documentation and help

1. Improving the developer experience

NodeJS tracker v0.4.0 improves the developer experience when using the NodeJS tracker and Snowplow Tracker Core functions in both JavaScript and TypeScript applications. Specifically, the following updates have been made:

• Bump snowplow-tracker-core to 0.9.1 (GitHub issue #58)
• Switch to RollupJS for building ES Module and CJS versions (GitHub issue #57)
• Add Typescript support (GitHub issue #13)

The types are bundled into the module available on NPM, so they should be available to you immediately.

2. Adding the domain_userid and the network_userid

You are now able to set the domain_userid and the network_userid in the NodeJS tracker (GitHub issues #23 and #24).

The domain_userid is Snowplow’s first party client side cookie ID. The network_userid is Snowplow’s server side cookie ID, and can be first or third party depending on how you configure your collector. More information on the Snowplow cookie IDs can be found in the technical documentation.

The methods are as follows:

setDomainUserId(); setNetworkUserId(); 

Examples of how to use these can be found in the NodeJS tracker documentation.

3. Support for the dvce_sent_tstamp

The NodeJS tracker now also supports the dvce_sent_tstamp (GitHub issue #27). This timestamp most precisely captures when the event occured on the device, and is used to calculate the derived_tstamp as follows:

derived_tstamp = collector_tstamp - (dvce_sent_tstamp - dvce_created_tstamp) 

Specifically, the derived_tstamp adjusts the dvce_sent_tstamp using the collector_tstamp to account for inaccurate device clocks. We recommend this is the timestamp you use in your analysis.

4. Switching to the got Emitter

This tracker version switches from using the deprecated ‘request’ library to the ‘got’ library (GitHub issue #61) for the emitter. This change comes with some additional emitter configuration options which you can find in the NodeJS tracker documentation.

Please note that got only works on NodeJS applications and does not have browser support. If the got library isn’t suitable for your project you can create your own emitter. For more information, please take a look at the documentation for creating your own emitter.

5. Breaking changes

Version 0.4.0 has the following breaking API changes:

• emitter is no longer available. You should switch from emitter to gotEmitter which continues to offer the same functionality but also includes a number of new features. For more information, please take a look at the gotEmitter documentation.
• If you are using trackEcommerceTransaction and passing in an array of items, you should now switch to using trackEcommerceTransactionWithItems. For more information, please take a look at the technical documentation.

6. Bug fixes

• Update flush to not send a request if the buffer is empty (GitHub issue #53)

7. Installation and upgrading

You can install the Snowplow Node.js Tracker with NPM or Yarn:

npm install snowplow-tracker 

or

yarn add snowplow-tracker 

If you are already using the snowplow-tracker library, and wish to upgrade, then as this is a pre-1.0.0 release you will need to force installation to the latest or specific version rather than using npm update.

npm install snowplow-tracker@latest 

To help with installation and/or upgrading, new API Documentation is also now available from this release here.

8. Documentation and help

For help on integrating the tracker please have a look at the setup guide. Information about how to use the tracker can be found in the NodeJS Tracker documentation. If you have any questions or run into any problems, please visit our Discourse forum.

You can find the full release notes on GitHub as Snowplow NodeJS Tracker v0.4.0 release.

Please raise any bugs in the NodeJS Tracker’s issues on GitHub.