Analytics
/

Analytics Plugins

How to install & use analytics plugins


The analytics library is extendable via plugins.

Analytics is an event driven system driven by a lifecycle. This lifecycle exposes hooks for plugins to react & alter default library behavior. Plugins can do a number of things like:

  • Add a new analytics provider destination for tracking, page views, & identifying visitors
  • Enhance / enrich data flowing to third party tools
  • Allow visitors to opt out of tracking & manage preferences
  • Add custom functionality to your app based on user behavior
  • Enforce analytic naming conventions & keep data clean
  • ... etc.

This guide will walk through installing & using plugins.

Supported Analytic Tools

Below is a list of supported analytic providers. If you don't see your analytic tools, you can build your own plugin or request a plugin

crazyeggcustomeriofullstorygoogle-analyticsgoogle-tag-managerhubspotsegmentsimple-analytics

Installation & Usage

  1. Install analytics & plugins

    Here we are installing analytics & the google tag manager plugin.

    npm install analytics
    npm install analytics-plugin-google-tag-manager
  2. Include analytics in your project

    Import analytics and any plugins you wish to use in the plugins array.

    Plugins need to be attached at initialization.

    /* analytics.js */
    import Analytics from 'analytics'
    import googleTagManager from 'analytics-plugin-google-tag-manager'
    
    // export analytics instance for use in app
    export default Analytics({
      app: 'app-name',
      plugins: [
        googleTagManager({
          containerId: 'GTM-xyz123'
        })
      ]
    })
  3. Use in code

    import analytics from './analytics'
    
    /* Track page views */
    analytics.page()
    
    /* Identify users */
    analytics.identify('userid-123', {
      favoriteColor: 'blue',
      membershipLevel: 'pro'
    })
    
    /* Track events */
    analytics.track('buttonClicked', {
      value: 100
    })

Selectively disabling plugins

You can disable specific page, track, identify calls from passing through an installed plugin.

In the options of the call, pass an plugins object and set the NAMESPACE of the plugin to false. This will disable the call from hitting that particular analytics service.

analytics.identify('xyz-123', {
  super: true,
  rad: 'dope'
}, {
  /* Disable the ‘vanilla’ plugin for this identify call */
  plugins: {
    vanilla: false
  }
})

Disabling plugins

You can disable plugins with the analytics.disablePlugin method. This will stop all track, page, and identify calls from sending to the plugin provider.

// Turn off google-analytics calls
analytics.disablePlugin(['google-analytics'])

Enable plugins

You can enable plugins with the analytics.enablePlugin method

// Turn on google-analytics calls
analytics.enablePlugin(['google-analytics'])

Adding Custom plugins

See the writing custom plugins section for building plugins to fit your use case.

Custom plugins can be added inline or via npm packages.