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 event naming conventions & keep data clean
• Listen & react to browser events
• ... 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

Installation & Usage

1. Install analytics & plugins

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

   Copy

   npm install analytics
   npm install @analytics/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 during initialization.

   Copy

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

3. Use in code

   Copy

   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 name 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.plugins.disable(['google-analytics'])

Enable plugins

You can enable plugins with the analytics.plugins.enable method

// Turn on google-analytics calls
analytics.plugins.enable(['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.