@analytics/snowplow v0.3.3

Snowplow plugin for analytics

Integration with Snowplow Analytics for analytics package.

View the docs

• 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

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

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.