@analytics/google-analytics NPM

Google Analytics

This analytics plugin will load google analytics v.4 into your application.

For more information see the docs.

Installation

npm install analytics
npm install @analytics/google-analytics

How to use

The @analytics/google-analytics package works in the browser. 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({
      measurementIds: ['G-abc123']
    })
  ]
})

/* 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'
})

After initializing analytics with the googleAnalytics plugin, data will be sent into Google Analytics whenever analytics.identify, analytics.page, or analytics.track 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

Browser usage

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

analytics.identify - Identify visitors and send details to Google Analytics
analytics.page - Sends page views into Google Analytics
analytics.track - Track custom events and send to Google Analytics

Browser API

import Analytics from 'analytics'
import googleAnalytics from '@analytics/google-analytics'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [
    googleAnalytics({
      measurementIds: ['G-abc123']
    })
  ]
})

Configuration options for browser

Option	description
`measurementIds` required - Array.	Google Analytics MEASUREMENT IDs
`debug` optional - boolean	Enable Google Analytics debug mode
`dataLayerName` optional - string	The optional name for dataLayer object. Defaults to ga4DataLayer.
`gtagName` optional - string	The optional name for dataLayer object. Defaults to `gtag`.
`gtagConfig.anonymize_ip` optional - boolean	Enable Anonymizing IP addresses sent to Google Analytics.
`gtagConfig.cookie_domain` optional - object	Additional cookie properties for configuring the ga cookie
`gtagConfig.cookie_expires` optional - object	Additional cookie properties for configuring the ga cookie
`gtagConfig.cookie_prefix` optional - object	Additional cookie properties for configuring the ga cookie
`gtagConfig.cookie_update` optional - object	Additional cookie properties for configuring the ga cookie
`gtagConfig.cookie_flags` optional - object	Additional cookie properties for configuring the ga cookie
`customScriptSrc` optional - string	Custom URL for google analytics script, if proxying calls

Additional examples

Below are additional implementation examples.

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({
            measurementIds: ['G-abc123']
          })
        ]
      })

      /* 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'
      })
    </script>
  </head>
  <body>
    ....
  </body>
</html>

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({
            measurementIds: ['G-abc123']
          })
          // ... add any other third party analytics 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'
      })
    </script>
  </head>
  <body>
    ....
  </body>
</html>

Fix "double page views"

Google analytics 4 sometimes automatically sends a page view for single page applications. To disable this you will need to go into the settings of your stream and click into "enhanced measurement" section and uncheck the "Page changes based on browser history events" setting. This will make sure only analytics.page() calls will send page views to Google analytics v4.

Legacy Google analytics v3

For the older version of google analytics please see the @analytics/google-analytics-v3 package or the GA3 plugin docs

Using GA3 and GA4 together

It is possible to use both GA3 and GA4 together shown below. Just remember GA3 will be deprecated starting in July of 2023

import Analytics from 'analytics'
import googleAnalyticsPlugin from '@analytics/google-analytics'
import googleAnalyticsV3Plugin from '@analytics/google-analytics-v3'

/* Initialize analytics instance */
const analytics = Analytics({
  app: 'my-app',
  plugins: [
    /* Load Google Analytics v4 */
    googleAnalyticsPlugin({
      measurementIds: ['G-abc123'],
    }),
    /* Load Google Analytics v3 */
    googleAnalyticsV3Plugin({
      trackingId: 'UA-11111111-2',
    }),
  ],
})

analytics.page()

analytics analytics-project analytics-plugin GA google-analytics Google Analytics