Analytics
/

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

EventDescription
bootstrapFires 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
paramsFires when analytics parses URL parameters
campaignFires if params contain "utm" parameters
initializeStartFires before 'initialize', allows for plugins to cancel loading of other plugins
initializeFires when analytics loads plugins
initializeEndFires after initialize, allows for plugins to run logic after initialization methods run
readyFires when all analytic providers are fully loaded. This waits for 'initialize' and 'loaded' to return true

Page Events

EventDescription
pageStartFires before 'page' events fire.
This allows for dynamic page view cancellation based on current state of user or options passed in.
pageCore analytics hook for page views.
If your plugin or integration tracks page views, this is the event to fire on.
pageEndFires after all registered 'page' methods fire.
pageAbortedFires if 'page' call is cancelled by a plugin

Track Events

EventDescription
trackStartCalled before the 'track' events fires.
This allows for dynamic page view cancellation based on current state of user or options passed in.
trackCore analytics hook for event tracking.
If your plugin or integration tracks custom events, this is the event to fire on.
trackEndFires after all registered 'track' events fire from plugins.
trackAbortedFires if 'track' call is cancelled by a plugin

Identify Events

EventDescription
identifyStartCalled before the 'identify' events fires.
This allows for dynamic page view cancellation based on current state of user or options passed in.
identifyCore analytics hook for user identification.
If your plugin or integration identifies users or user traits, this is the event to fire on.
identifyEndFires after all registered 'identify' events fire from plugins.
identifyAbortedFires if 'track' call is cancelled by a plugin
userIdChangedFires when a user id is updated

Storage Events

EventDescription
setItemStartFires when analytics.storage.setItem is initialized.
This event gives plugins the ability to intercept keys & values and alter them before they are persisted.
setItemFires when analytics.storage.setItem is called.
This event gives plugins the ability to intercept keys & values and alter them before they are persisted.
setItemEndFires when setItem storage is complete.
setItemAbortedFires when setItem storage is cancelled by a plugin.
removeItemStartFires when analytics.storage.removeItem is initialized.
This event gives plugins the ability to intercept removeItem calls and abort / alter them.
removeItemFires when analytics.storage.removeItem is called.
This event gives plugins the ability to intercept removeItem calls and abort / alter them.
removeItemEndFires when removeItem storage is complete.
removeItemAbortedFires when removeItem storage is cancelled by a plugin.

Network Events

EventDescription
onlineFires when browser network goes online.
This fires only when coming back online from an offline state.
offlineFires when browser network goes offline.

Other Events

EventDescription
resetStartFires if analytic.reset() is called.
Use this event to cancel reset based on a specific condition
resetFires if analytic.reset() is called.
Use this event to run custom cleanup logic (if needed)
resetEndFires after analytic.reset() is called.
Use this event to run a callback after user data is reset
registerPluginsFires when analytics is registering plugins
enablePluginFires when 'analytics.enablePlugin()' is called
disablePluginFires when 'analytics.disablePlugin()' is called
loadPluginFires 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