Neurophysiologically Pseudoscientific Manatee

    @analytics/google-analytics

    0.5.3 • Public • Published

    Google Analytics

    This library exports the google-analytics plugin for the analytics package & standalone methods for any project to use to make it easier to interact with Google Analytics.

    This analytics plugin will load google analytics into your application.

    For more information see the docs.

    Click to expand

    Installation

    npm install analytics
    npm install @analytics/google-analytics

    How to use

    The @analytics/google-analytics 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 googleAnalytics from '@analytics/google-analytics'
    
    const analytics = Analytics({
      app: 'awesome-app',
      plugins: [
        googleAnalytics({
          trackingId: 'UA-1234567'
        })
      ]
    })
    
    /* Track a page view */
    analytics.page()
    
    /* Track a custom event */
    analytics.track('playedVideo', {
      category: 'Videos',
      label: 'Fall Campaign',
      value: 42
    })
    
    /* Identify a visitor */
    analytics.identify('user-id-xyz', {
      firstName: 'bill',
      lastName: 'murray'
    })

    After initializing analytics with the googleAnalytics plugin, data will be sent into Google 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/google-analytics package works in the browser and server-side in Node.js

    Browser usage

    The Google Analytics client side browser plugin works with these analytic api methods:

    Browser API

    import Analytics from 'analytics'
    import googleAnalytics from '@analytics/google-analytics'
    
    const analytics = Analytics({
      app: 'awesome-app',
      plugins: [
        googleAnalytics({
          trackingId: 'UA-1234567'
        })
      ]
    })

    Configuration options for browser

    Option description
    trackingId
    required - string
    Google Analytics site tracking Id
    debug
    optional - boolean
    Enable Google Analytics debug mode
    anonymizeIp
    optional - boolean
    Enable Anonymizing IP addresses sent to Google Analytics. See details below
    customDimensions
    optional - object
    Map Custom dimensions to send extra information to Google Analytics. See details below
    resetCustomDimensionsOnPage
    optional - object
    Reset custom dimensions by key on analytics.page() calls. Useful for single page apps.
    setCustomDimensionsToPage
    optional - boolean
    Mapped dimensions will be set to the page & sent as properties of all subsequent events on that page. If false, analytics will only pass custom dimensions as part of individual events
    instanceName
    optional - string
    Custom tracker name for google analytics. Use this if you need multiple googleAnalytics scripts loaded
    customScriptSrc
    optional - string
    Custom URL for google analytics script, if proxying calls
    cookieConfig
    optional - object
    Additional cookie properties for configuring the ga cookie
    tasks
    optional - object
    Set custom google analytic tasks

    Server-side usage

    The Google Analytics server-side node.js plugin works with these analytic api methods:

    Server-side API

    import Analytics from 'analytics'
    import googleAnalytics from '@analytics/google-analytics'
    
    const analytics = Analytics({
      app: 'awesome-app',
      plugins: [
        googleAnalytics({
          trackingId: '123-xyz'
        })
      ]
    })

    Configuration options for server-side

    Option description
    trackingId
    required - string
    Google Analytics site tracking Id

    Additional examples

    Below are additional implementation examples.

    Server-side ES6
    import Analytics from 'analytics'
    import googleAnalytics from '@analytics/google-analytics'
    
    const analytics = Analytics({
      app: 'awesome-app',
      plugins: [
        googleAnalytics({
          trackingId: '123-xyz'
        })
        // ...other plugins
      ]
    })
    
    /* Track a page view */
    analytics.page()
    
    /* Track a custom event */
    analytics.track('cartCheckout', {
      item: 'pink socks',
      price: 20
    })
    
    /* 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 googleAnalytics = require('@analytics/google-analytics').default
    
    const analytics = analyticsLib({
      app: 'my-app-name',
      plugins: [
        googleAnalytics({
          trackingId: '123-xyz'
        })
      ]
    })
    
    /* Track a page view */
    analytics.page()
    
    /* Track a custom event */
    analytics.track('cartCheckout', {
      item: 'pink socks',
      price: 20
    })
    
    /* 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/google-analytics in HTML</title>
        <script src="https://unpkg.com/analytics/dist/analytics.min.js"></script>
        <script src="https://unpkg.com/@analytics/google-analytics/dist/@analytics/google-analytics.min.js"></script>
        <script type="text/javascript">
          /* Initialize analytics */
          var Analytics = _analytics.init({
            app: 'my-app-name',
            plugins: [
              analyticsGa.init({
                trackingId: 'UA-1234567'
              })
            ]
          })
    
          /* Track a page view */
          analytics.page()
    
          /* Track a custom event */
          analytics.track('playedVideo', {
            category: 'Videos',
            label: 'Fall Campaign',
            value: 42
          })
    
          /* Identify a visitor */
          analytics.identify('user-id-xyz', {
            firstName: 'bill',
            lastName: 'murray'
          })
        </script>
      </head>
      <body>
        ....
      </body>
    </html>
    Using in HTML via ES Modules

    Using @analytics/google-analytics in ESM modules.

    <!DOCTYPE html>
    <html>
      <head>
        <title>Using @analytics/google-analytics 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 analyticsGa from 'https://unpkg.com/@analytics/google-analytics/lib/analytics-plugin-ga.browser.es.js?module'
          /* Initialize analytics */
          const Analytics = analytics({
            app: 'analytics-html-demo',
            debug: true,
            plugins: [
              analyticsGa({
                trackingId: 'UA-1234567'
              })
              // ... add any other third party analytics plugins
            ]
          })
    
          /* Track a page view */
          analytics.page()
    
          /* Track a custom event */
          analytics.track('playedVideo', {
            category: 'Videos',
            label: 'Fall Campaign',
            value: 42
          })
    
          /* Identify a visitor */
          analytics.identify('user-id-xyz', {
            firstName: 'bill',
            lastName: 'murray'
          })
        </script>
      </head>
      <body>
        ....
      </body>
    </html>

    Anonymize Visitor IPs

    Google analytics allows you to anonymize visitor IP addresses.

    To anonymize the IP addresses of your visitors set the anonymizeIp configuration option.

    import Analytics from 'analytics'
    import googleAnalytics from '@analytics/google-analytics'
    
    /* initialize analytics */
    const analytics = Analytics({
      app: 'awesome-app',
      plugins: [
        googleAnalytics({
          trackingId: 'UA-1223141231',
          /* Anonymize the IP addresses */
          anonymizeIp: true
        }),
      ]
    })

    Customizing event payloads

    To send tracking custom events to Google Analytics with eventLabel, eventCategory, and eventValue fields, add the label, category, and value keys to the event properties.

    analytics.track('play', {
      category: 'Videos',
      label: 'Fall Campaign',
      value: 42
    })

    Using GA Custom Dimensions

    To use Google Analytics custom dimensions, use the customDimensions configuration option and map the values to the custom dimension slots.

    Set the "customDimensions" option

    When initializing analytics, make sure you set customDimensions and map your values.

    import Analytics from 'analytics'
    import googleAnalytics from '@analytics/google-analytics'
    
    /* initialize analytics */
    const analytics = Analytics({
      app: 'awesome-app',
      plugins: [
        googleAnalytics({
          trackingId: 'UA-1223141231',
          /* Map your Google Analytics custom dimensions here */
          customDimensions: {
            baz: 'dimension1',
            foo: 'dimension2',
            flam: 'dimension3',
          },
        }),
      ]
    })

    The above config will map baz to dimension1, foo to dimension2, and flam to dimension3

    When track, page, or identify calls are made, the mapped values will automatically set to Google Analytics custom dimensions.

    /* Tracking example */
    analytics.track('buttonClicked', {
       baz: 'hello', // baz is mapped to GA custom dimension "dimension1"
       foo: 'cool'   // foo is mapped to GA custom dimension "dimension2"
    })

    Under the hood, analytics automatically sets the custom dimensions in Google Analytics like so:

    window.ga('set', {dimension1: 'hello', dimension2: 'cool'})

    This also works with page & identify calls.

    /* Identify example */
    analytics.identify('user123', {
       flam: 'wow' // flam is mapped to GA custom dimension "dimension3"
    })
    
    // This is mapped to window.ga('set', {  dimension3: 'wow' })

    Using multiple instances

    While not advised, it's possible to use multiple Google Analytics instances on a single site.

    To use more than one google analytics instance in an app use the instanceName config field and make sure to override the default plugin name.

    Here is an example of using 2 Google Analytics instances in an app.

    import Analytics from 'analytics'
    import googleAnalytics from '@analytics/google-analytics'
    
    // Normal google analytics instance
    const instanceOne = googleAnalytics({
      trackingId: '123-xyz',
    })
    
    // Second google analytics instance with override for 'name' field of the plugin
    const instanceTwo = {
      // initialize the 2nd instance with 'instanceName' field set
      ...googleAnalytics({
        trackingId: '567-abc',
        instanceName: 'two'
      }),
      // change 'name' plugin to avoid namespace collisions
      ...{
        name: 'google-analytics-two'
      }
    }
    
    /* Object.assign example
    const instanceTwo = Object.assign({}, googleAnalytics({
        trackingId: '567-abc',
        instanceName: 'two'
      }), {
        name: 'google-analytics-two'
      }
    }) */
    
    const analytics = Analytics({
      app: 'awesome-app',
      plugins: [
        // Instance 1 of Google Analytics
        instanceOne,
        // Instance 2 of Google Analytics
        instanceTwo
      ]
    })

    Using the above configuration all tracking, page views, and identify calls will flow into both Google Analytics accounts.

    Custom Proxy Endpoint

    In specific scenarios, you might want to load your own version of google analytics to send requests to a proxy.

    To do this, you can add the customScriptSrc option pointing to your custom Google Analytics script.

    import Analytics from 'analytics'
    import googleAnalytics from '@analytics/google-analytics'
    
    const analytics = Analytics({
      app: 'awesome-app',
      plugins: [
        googleAnalytics({
          trackingId: '123-xyz',
          customScriptSrc: 'https://my-url.com/to-custom-ga.js'
        })
      ]
    })

    If using a proxied endpoint, it is recommended to combine this technique with the do-not-track plugin to ensure website visitors privacy.

    Electron Apps & Browser Extensions

    Electron apps bundle and serve their code from the file:// extension. Likewise, browser extensions serve files from chrome-extension://. This causes issues like this & this with Google Analytics.

    To fix chrome extensions, use the tasks configuration and set checkProtocolTask to null.

    To fix electron apps, use the tasks configuration option described below and set checkProtocolTask, checkStorageTask, & historyImportTask to null.

    Here is an example:

    import Analytics from 'analytics'
    import googleAnalytics from '@analytics/google-analytics'
    
    /* initialize analytics and load plugins */
    const analytics = Analytics({
      app: 'my-app',
      plugins: [
        googleAnalytics({
          trackingId: '123-xyz',
          // Override or disable GA Tasks https://bit.ly/31Xetmg
          tasks: {
            // Set checkProtocolTask, checkStorageTask, & historyImportTask for electron apps
            checkProtocolTask: null,
            checkStorageTask: null,
            historyImportTask: null,
          }
        }),
      ]
    })

    Custom GA Tasks

    In specific scenarios, you might need to disable or alter the default Google Analytic Tasks.

    For example, you might want to cancel a request or enrich it. You can do this via analytics plugins or use the tasks config option on GA plugin for access to the tracker instance for GA only.

    The tasks that can be hooked into are listed below & in the GA task docs

    • customTask By default, this task does nothing. Override it to provide custom behavior.
    • previewTask Aborts the request if the page is only being rendered to generate a 'Top Sites' thumbnail for Safari.
    • checkProtocolTask Aborts the request if the page protocol is not http or https.
    • validationTask Aborts the request if required fields are missing or invalid.
    • checkStorageTask Aborts the request if the tracker is configured to use cookies but the user's browser has cookies disabled.
    • historyImportTask Imports info from ga.js/urchin.js cookies to preserve history when a site migrates to Universal Analytics.
    • samplerTask Samples out visitors based on the sampleRate setting for this tracker.
    • buildHitTask Builds a measurement protocol request string and stores it in the hitPayload field.
    • sendHitTask Transmits the measurement protocol request stored in the hitPayload field to Google Analytics servers.
    • timingTask Automatically generates a site speed timing hit based on the siteSpeedSampleRate setting for this tracker.
    • displayFeaturesTask Sends an additional hit if display features is enabled & a previous hit has not been sent within the timeout period set by the advertising features cookie (_gat).
    import Analytics from 'analytics'
    import googleAnalytics from '@analytics/google-analytics'
    
    /* initialize analytics and load plugins */
    const analytics = Analytics({
      app: 'cool-app',
      plugins: [
        googleAnalytics({
          trackingId: '123-xyz',
          // Override or disable GA Tasks https://bit.ly/31Xetmg
          tasks: {
            // https://developers.google.com/analytics/devguides/collection/analyticsjs/tasks#adding_to_a_task
            sendHitTask: function (tracker) {
              // Save original Task
              var originalTask = tracker.get('sendHitTask')
              // Modifies sendHitTask to send a copy of the request to a local server after
              tracker.set('sendHitTask', function (model) {
                // 1. Send the normal request to www.google-analytics.com/collect.
                originalTask(model);
                // 2. Send to local server
                var xhr = new XMLHttpRequest();
                xhr.open('POST', '/localhits', true);
                xhr.send(model.get('hitPayload'));
              })
            },
            // https://developers.google.com/analytics/devguides/collection/analyticsjs/tasks#aborting_task_processing
            buildHitTask: (tracker) => {
              // Save original Task
              const originalBuildHitTask = tracker.get('buildHitTask')
              // Set custom buildHitTask with abort
              tracker.set('buildHitTask', function (model) {
                if (document.cookie.match(/testing=true/)) {
                  throw new Error('Aborted tracking for test user.')
                }
                originalBuildHitTask(model);
              })
            },
          }
        }),
      ]
    })

    Cookie Config

    Some situations require changing the cookie properties of the Google Analytics cookie itself.

    The GA Cookie fields that are available are:

    Field Name Value Type Default value Description
    cookieName text _ga Name of the cookie used to store analytics data
    cookieDomain text The result of the following JavaScript expression: document.location.hostname Specifies the domain used to store the analytics cookie. Setting this to 'none' sets the cookie without specifying a domain.
    cookieExpires integer 63072000 (two years, in seconds) Specifies the cookie expiration, in seconds.
    cookieUpdate boolean true When cookieUpdate is set to true (the default value), analytics.js will update cookies on each page load. This will update the cookie expiration to be set relative to the most recent visit to the site.
    cookieFlags text Specifies additional flags to append to the cookie. Flags must be separated by semicolons.

    You can add these properties in the cookieConfig on the plugin config.

    import Analytics from 'analytics'
    import googleAnalytics from '@analytics/google-analytics'
    
    const analytics = Analytics({
      app: 'awesome-app',
      plugins: [
        googleAnalytics({
          trackingId: 'UA-1234567',
          cookieConfig: {
            cookieName: 'gaCookie',
            cookieDomain: 'blog.example.co.uk',
            cookieExpires: 60 * 60 * 24 * 28,  // Time in seconds.
            cookieUpdate: 'false',
            cookieFlags: 'SameSite=None; Secure',
          }
        })
      ]
    })

    Install

    npm i @analytics/google-analytics

    DownloadsWeekly Downloads

    22,317

    Version

    0.5.3

    License

    MIT

    Unpacked Size

    96.3 kB

    Total Files

    10

    Last publish

    Collaborators

    • davidwells