Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
executable file 277 lines (193 sloc) 8.02 KB
title description pageTitle subTitle
Getting started with Analytics
Start here to learn how to build apps with the analytics npm module
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 examples

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

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

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 & it's source code.

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()
You can’t perform that action at this time.