Getting Started

This guide will walk you through installing & wiring up analytics in your application.

Analytics is designed to work with any frontend javascript framework and it works in plain static HTML. For framework specific implementation examples checkout the main repo.

Let's jump into it 👇

1. Install the package

Install the analytics module into your project via npm

npm install analytics

Or install via yarn

yarn add analytics

2. Include in project

Import analytics and initialize the library with the analytics plugins of your choice.

/* example file src/analytics.js */
import Analytics from 'analytics'
const analytics = Analytics({
  app: 'app-name',
  plugins: [
    // ... your analytics integrations
  ]
})

/* export the instance for usage in your app */
export default analytics

See the configuration docs for more details.

3. Connect plugins

Connect analytics with a third-party analytics tool

To connect analytics to your third-party tools (e.g. Google analytics), install the provider plugin.

If there is no plugin for your provider, you can create a plugin or send us a request.

The example below is showing how to connect google analytics using the google analytics plugin.

This plugin will load the google analytics tracking script onto the page and handle page + custom event tracking.

/* src/analytics.js */
import Analytics from 'analytics'
import googleAnalytics from '@analytics/google-analytics'

const analytics = Analytics({
  app: 'app-name',
  plugins: [    googleAnalytics({      trackingId: 'UA-121991123',    })  ]})

export default analytics

4. Use in your app

After we've initialized analytics, we need to call the core methods in our application code.

Import the analytics instance created in the previous step and call a method:

• analytics.page() to send page view data.
• analytics.track() to send tracking events to your analytic providers
• analytics.identify to identify a website visitor

// Import analytics instance into your app and call its methods
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
})

See the api docs for further details:

• Page
• Track
• Identify

Usage examples

Analytics works in the browser and on the server in node.js.

In the browser, analytics will work with any frontend framework.

• HTML
• React
• Gatsby
• Preact
• Vue
• Angular

HTML

Analytics works in vanilla HTML pages and can be imported from a CDN.

Live demo & the source code.

React

Checkout the using analytics with react demo & the source code

For a larger example see the kitchen sink example & its source code.

Also checkout the useAnalytics react hooks.

Gatsby

To use analytics with Gatsby install the gatsby-plugin-analytics plugin.

Live demo (this site) & the source code.

npm install gatsby-plugin-analytics

And add to your gatsby.config.js file. This will enable automate page tracking.

{
  resolve: 'gatsby-plugin-analytics'
}

See the gatsby-plugin-analytics docs for more details.

You can also reference the various react examples above and directly integrate with a pushState listener in your site.

Preact

Preact is a fast 3kB alternative to React with the same modern API.

Using analytics with preact demo & the source code.

Vue

Using analytics with vue demo & the source code.

Angular

Demo coming soon. The above steps will work for Vue apps.

(contributions to the docs welcome 😃).

ES6 Usage

import Analytics from 'analytics'
import googleAnalyticsPlugin from '@analytics/google-analytics'
import customerIOPlugin from '@analytics/customerio'

/* Initialize analytics */
const analytics = Analytics({
  app: 'my-app-name',
  version: 100,
  plugins: [
    googleAnalyticsPlugin({
      trackingId: 'UA-121991291',
    }),
    customerIOPlugin({
      siteId: '123-xyz'
    })
  ]
})

/* Track a page view */
analytics.page()

/* Track a custom event */
analytics.track('userPurchase', {
  price: 20
  item: 'pink socks'
})

/* Identify a visitor */
analytics.identify('user-id-xyz', {
  firstName: 'bill',
  lastName: 'murray',
  email: 'da-coolest@aol.com'
})

CDN Browser usage

When importing global analytics into your project from a cdn the library is expose via a global _analytics variable.

Call _analytics.init to create an analytics instance.

<script src="https://unpkg.com/analytics/dist/analytics.min.js"></script>
<script>
  const Analytics = _analytics.init({
    app: 'my-app-name',
    version: 100,
    ...plugins
  })

  Analytics.track()

  // optionally expose to window
  window.Analytics = Analytics
</script>

If you are including analytics from the unpkg CDN via a script tag, it's possible that ad-blockers like uBlock Origin might block the script from loading.

This only effects applications importing analytics from a CDN. This is because ad-block extensions will block any URL with the word analytics.

This causes problems! This has been observed in CodeSandbox as well with ad-block browser extensions enabled.

If you are including analytics via a script tag, it's advised to rename the path and host the analytics script yourself to avoid these issues.

Example:

<!-- updated script URL to avoid client breaking analytics -->
<script src="https://cdn.my-site.com/load-this.min.js"></script>

Node.js Usage

For ES6/7 javascript you can import Analytics from 'analytics' for normal node.js usage you can import like so:

const { Analytics } = require('analytics')
// or const Analytics = require('analytics').default

const analytics = Analytics({
  app: 'my-app-name',
  version: 100,
  plugins: [
    googleAnalyticsPlugin({
      trackingId: 'UA-121991291',
    }),
    customerIOPlugin({
      siteId: '123-xyz'
    })
  ]
})

// Fire a page view
analytics.page()