Analytics
/

Getting Started

Start here to learn how to build apps with the analytics


This guide will walk you though 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 your own 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 it's 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:

Usage in React

Checkout the using analytics with react demo & the source code

For a larger example see the kitchen sink example & it's source code.

Usage in HTML

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

Live demo & the source code.

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

Usage in Preact

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

Using analytics with preact demo & the source code.

Usage in Vue

Using analytics with vue demo & the source code.

Usage in 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>

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()