Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
135 lines (102 sloc) 6.45 KB
title pageTitle description
Analytics Lifecycle Events
Lifecycle Events
Using lifecycle events to add custom functionality

The analytics is library is driven by a series of lifecycle events. These events allow developers to extend & customize the library to fit any kind of tracking requirements.

Events can be hooked into by listeners in your app code or by plugins included at library initialization.

The lifecycle flows like so 👇, and continues depending on which methods are called by your application.

Analytics Lifecycle

Below is a list of events exposed by default. To see the events flowing through your setup, turn on debug mode or checkout the demo.

Initialization Events

Event Description
bootstrap Fires when analytics library starts up.
This is the first event fired. '.on/once' listeners are not allowed on bootstrap
Plugins can attach logic to this event
params Fires when analytics parses URL parameters
campaign Fires if params contain "utm" parameters
initializeStart Fires before 'initialize', allows for plugins to cancel loading of other plugins
initialize Fires when analytics loads plugins
initializeEnd Fires after initialize, allows for plugins to run logic after initialization methods run
ready Fires when all analytic providers are fully loaded. This waits for 'initialize' and 'loaded' to return true

Page Events

Event Description
pageStart Fires before 'page' events fire.
This allows for dynamic page view cancellation based on current state of user or options passed in.
page Core analytics hook for page views.
If your plugin or integration tracks page views, this is the event to fire on.
pageEnd Fires after all registered 'page' methods fire.
pageAborted Fires if 'page' call is cancelled by a plugin

Track Events

Event Description
trackStart Called before the 'track' events fires.
This allows for dynamic page view cancellation based on current state of user or options passed in.
track Core analytics hook for event tracking.
If your plugin or integration tracks custom events, this is the event to fire on.
trackEnd Fires after all registered 'track' events fire from plugins.
trackAborted Fires if 'track' call is cancelled by a plugin

Identify Events

Event Description
identifyStart Called before the 'identify' events fires.
This allows for dynamic page view cancellation based on current state of user or options passed in.
identify Core analytics hook for user identification.
If your plugin or integration identifies users or user traits, this is the event to fire on.
identifyEnd Fires after all registered 'identify' events fire from plugins.
identifyAborted Fires if 'track' call is cancelled by a plugin
userIdChanged Fires when a user id is updated

Storage Events

Event Description
setItemStart Fires when analytics.storage.setItem is initialized.
This event gives plugins the ability to intercept keys & values and alter them before they are persisted.
setItem Fires when analytics.storage.setItem is called.
This event gives plugins the ability to intercept keys & values and alter them before they are persisted.
setItemEnd Fires when setItem storage is complete.
setItemAborted Fires when setItem storage is cancelled by a plugin.
removeItemStart Fires when analytics.storage.removeItem is initialized.
This event gives plugins the ability to intercept removeItem calls and abort / alter them.
removeItem Fires when analytics.storage.removeItem is called.
This event gives plugins the ability to intercept removeItem calls and abort / alter them.
removeItemEnd Fires when removeItem storage is complete.
removeItemAborted Fires when removeItem storage is cancelled by a plugin.

Network Events

Event Description
online Fires when browser network goes online.
This fires only when coming back online from an offline state.
offline Fires when browser network goes offline.

Other Events

Event Description
resetStart Fires if analytic.reset() is called.
Use this event to cancel reset based on a specific condition
reset Fires if analytic.reset() is called.
Use this event to run custom cleanup logic (if needed)
resetEnd Fires after analytic.reset() is called.
Use this event to run a callback after user data is reset
registerPlugins Fires when analytics is registering plugins
enablePlugin Fires when 'analytics.enablePlugin()' is called
disablePlugin Fires when 'analytics.disablePlugin()' is called
loadPlugin Fires when 'analytics.loadPlugin()' is called

Example using Listeners

import analytics from './analytics'

analytics.on('trackEnd', () => {
  console.log('analytics.track() call has completed')
})

analytics.once('params', ({ payload }) => {
  console.log('Found url params', payload)
})

Example using Plugins

Plugins can attach to any exposed lifecycle events. This is how provider plugins work.

Here's a quick example:

import Analytics from 'analytics'

/* Your custom code */
const myCustomPlugin = {
  name: 'do-not-track',
  /* Hook into initializeStart. This is before third party scripts have loaded on the page */
  initializeStart: ({ abort, config }) => {
    return abort('Cancel the initialize call because of reason XYZ')
  },
  // ... attach additional functionality to other events
}


const analytics = Analytics({
  app: 'app-name',
  plugins: [
    myCustomPlugin
  ]
})

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

See the writing custom plugins guide

You can’t perform that action at this time.