@analytics/snowplow

			Stars	Issues	Version	Updated	Created	Size
	@analytics/snowplow		2,344	100	0.3.3	2 years ago	4 years ago

Snowplow plugin for analytics

Integration with Snowplow Analytics for analytics package.
View the docs
Click to expand

Installation
How to use
Platforms Supported
Browser usage

- Browser API - Configuration options for browser

Server-side usage

- Server-side API - Configuration options for server-side

Additional examples

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.
Server-side ES6
```js 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'

})
```

Server-side Node.js with common JS
If using node, you will want to import the .default
```js 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'

})
```

Using in HTML
Below is an example of importing via the unpkg CDN. Please note this will pull in the latest version of the package.
```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>

```

Using in HTML via ES Modules
Using @analytics/snowplow in ESM modules.
```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>

```

See the full list of analytics provider plugins in the main repo.

Downloads in past

Stats

Popular Searches

Readme

Installation

How to use

Platforms Supported

Browser usage

Browser API

Configuration options for browser

Server-side usage

Server-side API

Configuration options for server-side

Additional examples

@analytics/snowplow

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Readme

Installation

How to use

Platforms Supported

Browser usage

Browser API

Configuration options for browser

Server-side usage

Server-side API

Configuration options for server-side

Additional examples

Sick of boring JavaScript newsletters?

Downloads in past