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

    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.

    /* 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: [
          containerId: 'GTM-xyz123'
  3. Use in code

    import analytics from './analytics'
    /* Track page views */
    /* 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

Enable plugins

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

// Turn on google-analytics calls

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.