Narrating Prophetic Monks

    @analytics/snowplow

    0.3.3 • Public • Published

    Snowplow plugin for analytics

    Integration with Snowplow Analytics for analytics package.

    View the docs

    Click to expand

    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:

    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:

    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
    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

    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.

    <!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 in HTML via ES Modules

    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.

    Install

    npm i @analytics/snowplow

    DownloadsWeekly Downloads

    2,344

    Version

    0.3.3

    License

    MIT

    Unpacked Size

    474 kB

    Total Files

    10

    Last publish

    Collaborators

    • davidwells