@analytics/snowplow v0.3.3
Snowplow plugin for analytics
Integration with Snowplow Analytics for analytics package.
Installation
Install analytics
and @analytics/snowplow
packages
npm install analytics
npm install @analytics/snowplow
How to use
The @analytics/snowplow
package works in the browser and server-side in Node.js. To use, install the package, include in your project and initialize the plugin with analytics.
Below is an example of how to use the browser plugin.
import Analytics from 'analytics'
import snowplowPlugin from '@analytics/snowplow'
const analytics = Analytics({
app: 'awesome-app',
plugins: [
// Minimal recommended configuration
snowplowPlugin({
name: 'snowplow',
collectorUrl: 'collector.mysite.com',
trackerSettings: {
appId: 'myApp'
}
})
]
})
/* Track a page view */
// Enable some automatic tracking before page event
analytics.on('initialize:snowplow', ({ instance }) => {
instance.plugins.snowplow.enableActivityTracking(10, 10)
instance.plugins.snowplow.enableLinkClickTracking()
})
// Track page
analytics.page()
// or Track page view with additional entities
analytics.page({
contexts: [
{
schema: 'iglu:com.acme/blog_post/jsonschema/1-0-0',
data: {
title: 'Re-thinking the structure of event data',
category: 'Data Insights',
author: 'Cara Baestlein',
datePublished: '2020-01-24'
}
}
]
})
/* Track a custom event */
// Track structured event
analytics.track('playedVideo', {
category: 'Videos',
label: 'Fall Campaign',
value: 42
})
// or Track Self Describing event
analytics.track('selfDescribingEvent', {
schema: 'iglu:com.acme/video_played/jsonschema/1-0-0',
data: {
id: 42,
title: 'Fall Campaign'
}
})
// or Track Self Describing event with additional entities
analytics.track('selfDescribingEvent', {
schema: 'iglu:com.acme/video_played/jsonschema/1-0-0',
data: {
id: 42,
title: 'Fall Campaign',
videoTimestampInMs: 1104
},
contexts: [
{
schema: 'iglu:com.acme/product/jsonschema/1-0-0',
data: {
id: 'f9cb6cb6-5ca8-47a6-9035-d9c6ac13029e',
category: 'clothing',
subCategory: 'socks',
price: 3.99
}
}
]
})
// or Track Enchanced Ecommerce event with product context
analytics.track('EnhancedEcommerceProductContext', {
id: 'P12345',
name: 'Android Warhol T-Shirt',
list: 'Search Results',
brand: 'Google',
category: 'Apparel/T-Shirts',
variant: 'Black',
quantity: 1
})
analytics.track('EnhancedEcommerceAction', {
action: 'add'
})
/* Identify a visitor */
analytics.identify('user-id-xyz')
After initializing analytics
with the snowplowPlugin
plugin, data will be sent into Snowplow Analytics whenever analytics.page, analytics.track, or analytics.identify are called.
See additional implementation examples for more details on using in your project.
Platforms Supported
The @analytics/snowplow
package works in the browser and server-side in Node.js
Browser usage
The Snowplow Analytics client side browser plugin works with these analytic api methods:
- analytics.page - Sends page views into Snowplow Analytics
- analytics.reset - Reset browser storage cookies & localstorage for Snowplow Analytics values
- analytics.track - Track custom events and send to Snowplow Analytics
- analytics.identify - Identify visitors and send details to Snowplow Analytics
Browser API
import Analytics from 'analytics'
import snowplowPlugin from '@analytics/snowplow'
const analytics = Analytics({
app: 'awesome-app',
plugins: [
// Minimal recommended configuration
snowplowPlugin({
name: 'snowplow',
collectorUrl: 'collector.mysite.com',
trackerSettings: {
appId: 'myApp'
}
})
]
})
Configuration options for browser
Option | description |
---|---|
collectorUrl required - string | The URL to a Snowplow collector |
name optional - string | The name to identify this instance of the tracker, use if using multiple tracker instances ('snowplow' default) |
trackerSettings optional - Object | The arg map to pass to the Snowplow Tracker |
trackerSettings.appId optional - string | The appId to identify this application |
trackerSettings.platform optional - string | Platform of tracking ("web" default) |
trackerSettings.cookieDomain optional - string | Domain to set cookie against |
trackerSettings.discoverRootDomain optional - string | Automatically discover root domain |
trackerSettings.cookieName optional - string | Prefix for cookies ("sp" default) |
trackerSettings.cookieSameSite optional - string | SameSite cookie setting ("None" default) |
trackerSettings.cookieSecure optional - boolean | Secure cookie setting (true default) |
trackerSettings.encodeBase64 optional - boolean | Encode JSON objects as Base64 (true default) |
trackerSettings.respectDoNotTrack optional - bolean | Respect do not track (consider analytics-plugin-do-not-track) (false default) |
trackerSettings.eventMethod optional - string | Method to send events, GET, POST, Beacon (POST default) |
trackerSettings.bufferSize optional - number | Amount of events to buffer before sending (1 default) |
trackerSettings.maxPostBytes optional - number | Maximum size of POST or Beacon before sending (40000 default) |
trackerSettings.crossDomainLinker optional - string | function to configure which links to add cross domain linking |
trackerSettings.cookieLifetime optional - number | Cookie lifetime (63072000 default) |
trackerSettings.stateStorageStrategy optional - string | Use cookies and/or localstorage ("cookieAndLocalStorage" default) |
trackerSettings.maxLocalStorageQueueSize optional - number | Maximum numbers of events to buffer in localstorage to prevent filling local storage (1000 default) |
trackerSettings.resetActivityTrackingOnPageView optional - boolean | Flag to decide whether to reset page ping timers on virtual page view (true default) |
trackerSettings.connectionTimeout optional - boolean | The timeout, in milliseconds, before GET and POST requests will timeout (5000 default) (Snowplow JS 2.15.0+) |
trackerSettings.anonymousTracking optional - Object | Flag to enable anonymous tracking functionality (false default) |
trackerSettings.anonymousTracking.withSessionTracking optional - boolean | Flag to enable whether to continue tracking sessions in anonymous tracking mode (false default) |
trackerSettings.anonymousTracking.withServerAnonymisation optional - boolean | Flag which prevents collector from returning and capturing cookies and capturing ip address (false default) |
trackerSettings.contexts optional - Object | The auto contexts for each event |
trackerSettings.contexts.webPage optional - boolean | The webpage context, containing the page view id. (true default) |
trackerSettings.contexts.performanceTiming optional - boolean | Add performance timing information |
trackerSettings.contexts.clientHints optional - Object | Add Client Hint information (Snowplow JS 2.15.0+) |
trackerSettings.contexts.clientHints.includeHighEntropy optional - boolean | Capture High Entropy Client Hints (Snowplow JS 2.15.0+) |
trackerSettings.contexts.gaCookies optional - boolean | Add gaCookie information |
trackerSettings.contexts.geolocation optional - boolean | Add browser geolocation information |
trackerSettings.contexts.optimizelyXSummary optional - boolean | Add browser geolocation information |
trackerSettings.plugins optional - Array | Additional plugins to include at tracker initialisation. See https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers/browser-tracker/browser-tracker-v3-reference/plugins/ |
Server-side usage
The Snowplow Analytics server-side node.js plugin works with these analytic api methods:
- analytics.page - Sends page views into Snowplow Analytics
- analytics.track - Track custom events and send to Snowplow Analytics
- analytics.identify - Identify visitors and send details to Snowplow Analytics
Server-side API
import Analytics from 'analytics'
import snowplowPlugin from '@analytics/snowplow'
const analytics = Analytics({
app: 'awesome-app',
plugins: [
snowplowPlugin({
name: 'snowplow',
collectorUrl: 'collector.mysite.com',
appId: 'myApp'
})
]
})
Configuration options for server-side
Option | description |
---|---|
collectorUrl required - string | The URL to a Snowplow collector |
appId required - string | The appId to identify this application |
name optional - string | The name to identify this instance of the tracker ('snowplow' default) |
protocol optional - string | 'http' or 'https' ('https' default) |
port optional - string | collector port (80 or 443 default) |
method optional - string | The method to send events to collector, 'post' or 'get' ('post' default) |
bufferSize optional - string | Only send events once n are buffered. Defaults to 1 for GET requests and 10 for POST requests. |
retries optional - string | The number of times the tracker will try to resend an event. Defaults to 5. |
maxSockets optional - string | Node.js agentOptions object to tune performance (6 default) |
platform optional - string | Sets the platform https://bit.ly/302dSQy ('srv' default) |
screenResolution optional - object | Sets device screen resolution if available |
screenResolution.width optional - number | Positive Integer for screen width |
screenResolution.height optional - number | Positive Integer for screen height |
viewport optional - object | Sets device viewport if available |
viewport.width optional - number | Positive Integer for viewport width |
viewport.height optional - number | Positive Integer for viewprt height |
colorDepth optional - number | Positive Integer, in bits per pixel |
timezone optional - string | Set user’s timezone e.g. 'Europe/London' |
lang optional - string | Ser user's lang e.globalThis. 'en' |
Additional examples
Below are additional implementation examples.
import Analytics from 'analytics'
import snowplowPlugin from '@analytics/snowplow'
const analytics = Analytics({
app: 'awesome-app',
plugins: [
snowplowPlugin({
name: 'snowplow',
collectorUrl: 'collector.mysite.com',
appId: 'myApp'
})
// ...other plugins
]
})
/* Track a page view */
// Track page
analytics.page()
// or Track page view with additional entities
analytics.page({
contexts: [
{
schema: 'iglu:com.acme/blog_post/jsonschema/1-0-0',
data: {
title: 'Re-thinking the structure of event data',
url:
'https://snowplowanalytics.com/blog/2020/01/24/re-thinking-the-structure-of-event-data/',
category: 'Data Insights',
author: 'Cara Baestlein',
datePublished: '2020-01-24'
}
}
]
})
/* Track a custom event */
// Track structured event
analytics.track('playedVideo', {
category: 'Videos',
label: 'Fall Campaign',
value: 42
})
// or Track Self Describing event
analytics.track('selfDescribingEvent', {
schema: 'iglu:com.acme/video_played/jsonschema/1-0-0',
data: {
id: 42,
title: 'Fall Campaign'
}
})
// or Track Self Describing event with additional entities
analytics.track('selfDescribingEvent', {
schema: 'iglu:com.acme/video_played/jsonschema/1-0-0',
data: {
id: 42,
title: 'Fall Campaign',
videoTimestampInMs: 1104
},
contexts: [
{
schema: 'iglu:com.acme/product/jsonschema/1-0-0',
data: {
id: 'f9cb6cb6-5ca8-47a6-9035-d9c6ac13029e',
category: 'clothing',
subCategory: 'socks',
price: 3.99
}
}
]
})
// or Track Enchanced Ecommerce event with product context
analytics.track('ScreenView', {
name: 'Product Page',
id: 'p-123',
contexts: [
{
schema: 'iglu:com.acme/product/jsonschema/1-0-0',
data: {
id: 'f9cb6cb6-5ca8-47a6-9035-d9c6ac13029e',
category: 'clothing',
subCategory: 'socks',
price: 3.99
}
}
]
})
/* Identify a visitor */
analytics.identify('user-id-xyz', {
firstName: 'bill',
lastName: 'murray'
})
If using node, you will want to import the .default
const analyticsLib = require('analytics').default
const snowplowPlugin = require('@analytics/snowplow').default
const analytics = analyticsLib({
app: 'my-app-name',
plugins: [
snowplowPlugin({
name: 'snowplow',
collectorUrl: 'collector.mysite.com',
appId: 'myApp'
})
]
})
/* Track a page view */
// Track page
analytics.page()
// or Track page view with additional entities
analytics.page({
contexts: [
{
schema: 'iglu:com.acme/blog_post/jsonschema/1-0-0',
data: {
title: 'Re-thinking the structure of event data',
url:
'https://snowplowanalytics.com/blog/2020/01/24/re-thinking-the-structure-of-event-data/',
category: 'Data Insights',
author: 'Cara Baestlein',
datePublished: '2020-01-24'
}
}
]
})
/* Track a custom event */
// Track structured event
analytics.track('playedVideo', {
category: 'Videos',
label: 'Fall Campaign',
value: 42
})
// or Track Self Describing event
analytics.track('selfDescribingEvent', {
schema: 'iglu:com.acme/video_played/jsonschema/1-0-0',
data: {
id: 42,
title: 'Fall Campaign'
}
})
// or Track Self Describing event with additional entities
analytics.track('selfDescribingEvent', {
schema: 'iglu:com.acme/video_played/jsonschema/1-0-0',
data: {
id: 42,
title: 'Fall Campaign',
videoTimestampInMs: 1104
},
contexts: [
{
schema: 'iglu:com.acme/product/jsonschema/1-0-0',
data: {
id: 'f9cb6cb6-5ca8-47a6-9035-d9c6ac13029e',
category: 'clothing',
subCategory: 'socks',
price: 3.99
}
}
]
})
// or Track Enchanced Ecommerce event with product context
analytics.track('ScreenView', {
name: 'Product Page',
id: 'p-123',
contexts: [
{
schema: 'iglu:com.acme/product/jsonschema/1-0-0',
data: {
id: 'f9cb6cb6-5ca8-47a6-9035-d9c6ac13029e',
category: 'clothing',
subCategory: 'socks',
price: 3.99
}
}
]
})
/* Identify a visitor */
analytics.identify('user-id-xyz', {
firstName: 'bill',
lastName: 'murray'
})
Below is an example of importing via the unpkg CDN. Please note this will pull in the latest version of the package.
<!DOCTYPE html>
<html>
<head>
<title>Using @analytics/snowplow in HTML</title>
<script src="https://unpkg.com/analytics/dist/analytics.min.js"></script>
<script src="https://unpkg.com/@analytics/snowplow/dist/@analytics/snowplow.min.js"></script>
<script type="text/javascript">
/* Initialize analytics */
var Analytics = _analytics.init({
app: 'my-app-name',
plugins: [
// Minimal recommended configuration
analyticsSnowplow({
name: 'snowplow',
collectorUrl: 'collector.mysite.com',
trackerSettings: {
appId: 'myApp'
}
})
]
})
/* Track a page view */
// Enable some automatic tracking before page event
analytics.on('initialize:snowplow', ({ instance }) => {
instance.plugins.snowplow.enableActivityTracking(10, 10)
instance.plugins.snowplow.enableLinkClickTracking()
})
// Track page
analytics.page()
// or Track page view with additional entities
analytics.page({
contexts: [
{
schema: 'iglu:com.acme/blog_post/jsonschema/1-0-0',
data: {
title: 'Re-thinking the structure of event data',
category: 'Data Insights',
author: 'Cara Baestlein',
datePublished: '2020-01-24'
}
}
]
})
/* Track a custom event */
// Track structured event
analytics.track('playedVideo', {
category: 'Videos',
label: 'Fall Campaign',
value: 42
})
// or Track Self Describing event
analytics.track('selfDescribingEvent', {
schema: 'iglu:com.acme/video_played/jsonschema/1-0-0',
data: {
id: 42,
title: 'Fall Campaign'
}
})
// or Track Self Describing event with additional entities
analytics.track('selfDescribingEvent', {
schema: 'iglu:com.acme/video_played/jsonschema/1-0-0',
data: {
id: 42,
title: 'Fall Campaign',
videoTimestampInMs: 1104
},
contexts: [
{
schema: 'iglu:com.acme/product/jsonschema/1-0-0',
data: {
id: 'f9cb6cb6-5ca8-47a6-9035-d9c6ac13029e',
category: 'clothing',
subCategory: 'socks',
price: 3.99
}
}
]
})
// or Track Enchanced Ecommerce event with product context
analytics.track('EnhancedEcommerceProductContext', {
id: 'P12345',
name: 'Android Warhol T-Shirt',
list: 'Search Results',
brand: 'Google',
category: 'Apparel/T-Shirts',
variant: 'Black',
quantity: 1
})
analytics.track('EnhancedEcommerceAction', {
action: 'add'
})
/* Identify a visitor */
analytics.identify('user-id-xyz')
</script>
</head>
<body>
....
</body>
</html>
Using @analytics/snowplow
in ESM modules.
<!DOCTYPE html>
<html>
<head>
<title>Using @analytics/snowplow in HTML via ESModules</title>
<script>
// Polyfill process.
// **Note**: Because `import`s are hoisted, we need a separate, prior <script> block.
window.process = window.process || { env: { NODE_ENV: 'production' } }
</script>
<script type="module">
import analytics from 'https://unpkg.com/analytics/lib/analytics.browser.es.js?module'
import analyticsSnowplow from 'https://unpkg.com/@analytics/snowplow/lib/analytics-plugin-snowplow.browser.es.js?module'
/* Initialize analytics */
const Analytics = analytics({
app: 'analytics-html-demo',
debug: true,
plugins: [
// Minimal recommended configuration
analyticsSnowplow({
name: 'snowplow',
collectorUrl: 'collector.mysite.com',
trackerSettings: {
appId: 'myApp'
}
})
// ... add any other third party analytics plugins
]
})
/* Track a page view */
// Enable some automatic tracking before page event
analytics.on('initialize:snowplow', ({ instance }) => {
instance.plugins.snowplow.enableActivityTracking(10, 10)
instance.plugins.snowplow.enableLinkClickTracking()
})
// Track page
analytics.page()
// or Track page view with additional entities
analytics.page({
contexts: [
{
schema: 'iglu:com.acme/blog_post/jsonschema/1-0-0',
data: {
title: 'Re-thinking the structure of event data',
category: 'Data Insights',
author: 'Cara Baestlein',
datePublished: '2020-01-24'
}
}
]
})
/* Track a custom event */
// Track structured event
analytics.track('playedVideo', {
category: 'Videos',
label: 'Fall Campaign',
value: 42
})
// or Track Self Describing event
analytics.track('selfDescribingEvent', {
schema: 'iglu:com.acme/video_played/jsonschema/1-0-0',
data: {
id: 42,
title: 'Fall Campaign'
}
})
// or Track Self Describing event with additional entities
analytics.track('selfDescribingEvent', {
schema: 'iglu:com.acme/video_played/jsonschema/1-0-0',
data: {
id: 42,
title: 'Fall Campaign',
videoTimestampInMs: 1104
},
contexts: [
{
schema: 'iglu:com.acme/product/jsonschema/1-0-0',
data: {
id: 'f9cb6cb6-5ca8-47a6-9035-d9c6ac13029e',
category: 'clothing',
subCategory: 'socks',
price: 3.99
}
}
]
})
// or Track Enchanced Ecommerce event with product context
analytics.track('EnhancedEcommerceProductContext', {
id: 'P12345',
name: 'Android Warhol T-Shirt',
list: 'Search Results',
brand: 'Google',
category: 'Apparel/T-Shirts',
variant: 'Black',
quantity: 1
})
analytics.track('EnhancedEcommerceAction', {
action: 'add'
})
/* Identify a visitor */
analytics.identify('user-id-xyz')
</script>
</head>
<body>
....
</body>
</html>
See the full list of analytics provider plugins in the main repo.