Lightweight analytics library for tracking events, page views, & identifying users. Works with any third party analytics provider via an extendable plugin system.
The 'analytics' npm package is a lightweight, pluggable library for tracking events, user data, and more. It provides a simple API to integrate with various analytics services and manage user data.
Track Events
This feature allows you to track custom events within your application. The code sample demonstrates how to initialize the analytics instance with a Google Analytics plugin and track a 'buttonClicked' event.
const Analytics = require('analytics').default;
const googleAnalytics = require('@analytics/google-analytics').default;
const analytics = Analytics({
app: 'my-app',
plugins: [
googleAnalytics({
trackingId: 'UA-1234567'
})
]
});
analytics.track('buttonClicked', {
category: 'User Interaction',
label: 'Signup Button'
});Identify Users
This feature allows you to identify users and associate them with specific data. The code sample shows how to identify a user with a unique ID and additional user information.
const Analytics = require('analytics').default;
const googleAnalytics = require('@analytics/google-analytics').default;
const analytics = Analytics({
app: 'my-app',
plugins: [
googleAnalytics({
trackingId: 'UA-1234567'
})
]
});
analytics.identify('user-id-123', {
name: 'John Doe',
email: 'john.doe@example.com'
});Page Views
This feature allows you to track page views within your application. The code sample demonstrates how to initialize the analytics instance and track a page view.
const Analytics = require('analytics').default;
const googleAnalytics = require('@analytics/google-analytics').default;
const analytics = Analytics({
app: 'my-app',
plugins: [
googleAnalytics({
trackingId: 'UA-1234567'
})
]
});
analytics.page();Segment is a customer data platform that helps you collect, clean, and control your customer data. It offers a more comprehensive suite of tools and integrations compared to 'analytics', making it suitable for larger enterprises.
Mixpanel is an advanced analytics service that helps you track user interactions with web and mobile applications. It provides more in-depth analysis and visualization tools compared to 'analytics'.
Amplitude is a product analytics service that helps you understand user behavior and optimize your product. It offers more robust analytics and reporting features compared to 'analytics'.
A lightweight, extendable analytics library designed to work with any third party analytics provider to track page views, custom events, & identify users.
The analytics library allows users to:
Companies frequently change analytics & collection requirements. This results in adding & removing analytic services a painful time consuming process.
This library aims to solves that with a simple pluggable abstraction layer.
You should never be locked into a tool
To add or remove an analytics provider adjust the plugins you load into analytics.
npm install analytics --save
Or as a script tag:
<script src="https://unpkg.com/analytics/dist/analytics.min.js"></script>
import Analytics from 'analytics'
import googleAnalyticsPlugin from 'analytics-plugin-ga'
import customerIOPlugin from 'analytics-plugin-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'
})
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()
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>
See Analytics Demo for a site example.
Below is the core API analytics expose once initialized.
Analytics library
Arguments
object - analytics core configstring - Name of site / appstring - Version of your apparray - Array of analytics pluginsExample
import Analytics from 'analytics'
// initialize analytics
const analytics = Analytics({
app: 'my-awesome-app',
plugins: [
...importedPlugins
]
})
Identify a user. This will trigger identify calls in any installed plugins and will set user data in localStorage
Arguments
String - Unique ID of userObject - Object of user traitsObject - Options to pass to identify callFunction - Callback function after identify completesExample
// Basic user id identify
analytics.identify('xyz-123')
// Identify with additional traits
analytics.identify('xyz-123', {
name: 'steve',
company: 'hello-clicky'
})
// Disable identify for specific plugin
analytics.identify('xyz-123', {}, {
plugins: {
// disable for segment plugin
segment: false
}
})
// Fire callback with 2nd or 3rd argument
analytics.identify('xyz-123', () => {
console.log('do this after identify')
})
Track an analytics event. This will trigger track calls in any installed plugins
Arguments
String - Event nameObject - Event payloadObject - Event optionsFunction - Callback to fire after tracking completesExample
// Basic event tracking
analytics.track('buttonClicked')
// Event tracking with payload
analytics.track('itemPurchased', {
price: 11,
sku: '1234'
})
// Disable specific plugin on track
analytics.track('cartAbandoned', {
items: ['xyz', 'abc']
}, {
plugins: {
// disable track event for segment
segment: false
}
})
// Fire callback with 2nd or 3rd argument
analytics.track('newsletterSubscribed', () => {
console.log('do this after track')
})
Trigger page view. This will trigger page calls in any installed plugins
Arguments
String - Page data overrides.Object - Page tracking optionsFunction - Callback to fire after page view call completesExample
// Basic page tracking
analytics.page()
// Page tracking with page data overides
analytics.page({
url: 'https://google.com'
})
// Disable specific plugin page tracking
analytics.page({}, {
plugins: {
// disable page tracking event for segment
segment: false
}
})
// Fire callback with 1st, 2nd or 3rd argument
analytics.page(() => {
console.log('do this after page')
})
Get user data
Arguments
String - dot.prop.path of user data. Example: 'traits.company.name'Example
// Get all user data
const userData = analytics.user()
// Get user id
const userId = analytics.user('userId')
// Get user company name
const companyName = analytics.user('traits.company.name')
Clear all information about the visitor & reset analytic state.
Arguments
Function - Handler to run after resetExample
// Reset current visitor
analytics.reset()
Fire callback on analytics ready event
Arguments
Function - function to trigger when all providers have loadedExample
analytics.ready() => {
console.log('all plugins have loaded or were skipped', payload)
})
Attach an event handler function for analytics lifecycle events.
Arguments
String - Name of event to listen toFunction - function to fire on eventExample
// Fire function when 'track' calls happen
analytics.on('track', ({ payload }) => {
console.log('track call just happened. Do stuff')
})
// Remove listener before it is called
const removeListener = analytics.on('track', ({ payload }) => {
console.log('This will never get called')
})
// cleanup .on listener
removeListener()
Attach a handler function to an event and only trigger it only once.
Arguments
String - Name of event to listen toFunction - function to fire on eventExample
// Fire function only once 'track'
analytics.once('track', ({ payload }) => {
console.log('This will only triggered once when analytics.track() fires')
})
// Remove listener before it is called
const listener = analytics.once('track', ({ payload }) => {
console.log('This will never get called b/c listener() is called')
})
// cleanup .once listener before it fires
listener()
Get data about user, activity, or context. Access sub-keys of state with dot.prop syntax.
Arguments
string - dot.prop.path value of stateExample
// Get the current state of analytics
analytics.getState()
// Get a subpath of state
analytics.getState('context.offline')
Enable analytics plugin
Arguments
String|Array - name of plugins(s) to disableFunction - callback after enable runsExample
analytics.enablePlugin('google')
// Enable multiple plugins at once
analytics.enablePlugin(['google', 'segment'])
Disable analytics plugin
Arguments
String|Array - name of integration(s) to disableFunction - callback after disable runsExample
analytics.disablePlugin('google')
analytics.disablePlugin(['google', 'segment'])
Storage utilities for persisting data. These methods will allow you to save data in localStorage, cookies, or to the window.
Example
// Pull storage off analytics instance
const { storage } = analytics
// Get value
storage.getItem('storage_key')
// Set value
storage.setItem('storage_key', 'value')
// Remove value
storage.removeItem('storage_key')
Get value from storage
Arguments
String - storage keyObject - storage optionsExample
analytics.storage.getItem('storage_key')
Set storage value
Arguments
String - storage keyObject - storage optionsExample
analytics.storage.setItem('storage_key', 'value')
Remove storage value
Arguments
String - storage keyObject - storage optionsExample
analytics.storage.removeItem('storage_key')
The analytics library comes with a large variety of event listeners that can be used to fire custom functionality when a specific lifecycle event occurs.
These listeners can be fired using analytics.on & analytics.once
const eventName = 'pageEnd'
analytics.on(eventName, ({ payload }) => {
console.log('payload', payload)
})
Below is a list of the current available 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 |
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 |
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 |
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 |
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 |
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 |
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. |
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. |
The analytics has a robust plugin system. Here is a list of currently available plugins:
analytics pkg npm link.The library is designed to work with any third party analytics tool.
Plugins are just plain javascript objects that expose methods for analytics to register and call.
Here is a quick example of a plugin:
// plugin-example.js
export default function pluginExample(userConfig) {
// return object for analytics to use
return {
/* All plugins require a NAMESPACE */
NAMESPACE: 'my-example-plugin',
/* Everything else below this is optional depending on your plugin requirements */
config: {
whatEver: userConfig.whatEver,
elseYouNeed: userConfig.elseYouNeed
},
initialize: ({ config }) => {
// load provider script to page
},
page: ({ payload }) => {
// call provider specific page tracking
},
track: ({ payload }) => {
// call provider specific event tracking
},
identify: ({ payload }) => {
// call provider specific user identify method
},
loaded: () => {
// return boolean so analytics knows when it can send data to third party
return !!window.myPluginLoaded
}
}
}
NAMESPACE is required for all plugins. All other methods are optional.
If you don't need to hook into page tracking, just omit the page key from your plugin object.
To use a plugin, import it and pass it into the plugins array when you bootstrap analytics.
import Analytics from 'analytics'
import pluginExample from './plugin-example.js'
const analytics = Analytics({
app: 'my-app-name',
plugins: [
pluginExample({
whatEver: 'hello',
elseYouNeed: 'there'
}),
...otherPlugins
]
})
Plugins can react to any event flowing through the analytics library.
For example, if you wanted to trigger custom logic when analytics bootstraps you can attach a function handler to the bootstrap event.
For a full list of core events, checkout events.js.
// Example Plugin plugin.js
export default function myPlugin(userConfig) {
return {
NAMESPACE: 'my-plugin',
bootstrap: ({ payload, config, instance }) => {
// Do whatever on `bootstrap` event
},
pageStart: ({ payload, config, instance }) => {
// Fire custom logic before analytics.page() calls
},
pageEnd: ({ payload, config, instance }) => {
// Fire custom logic after analytics.page() calls
},
trackStart: ({ payload, config, instance }) => {
// Fire custom logic before analytics.track() calls
},
'track:customerio': ({ payload, config, instance }) => {
// Fire custom logic before customer.io plugin runs.
// Here you can customize the data sent to individual analytics providers
},
trackEnd: ({ payload, config, instance }) => {
// Fire custom logic after analytics.track() calls
},
// ... hook into other events
}
}
Using this plugin is the same as any other.
import Analytics from 'analytics'
import customerIoPlugin from 'analytics-plugin-customerio'
import myPlugin from './plugin.js'
const analytics = Analytics({
app: 'my-app-name',
plugins: [
// include myPlugin
myPlugin(),
customerIoPlugin({
trackingId: '1234'
})
...otherPlugins
]
})
Alternatively, you can also attach any middleware functionality you'd like from the redux ecosystem.
// logger-plugin.js redux middleware
const logger = store => next => action => {
if (action.type) {
console.log(`>> analytics dispatching ${action.type}`, JSON.stringify(action))
}
return next(action)
}
export default logger
Using this plugin is the same as any other.
import Analytics from 'analytics'
import loggerPlugin from './logger-plugin.js'
const analytics = Analytics({
app: 'my-app-name',
plugins: [
...otherPlugins,
loggerPlugin
]
})
This is a vanilla redux middleware that will opt out users from tracking. There are many ways to implement this type of functionality using analytics
const optOutMiddleware = store => next => action => {
const { type } = action
if (type === 'trackStart' || type === 'pageStart' || type === 'trackStart') {
// Check cookie/localStorage/Whatever to see if visitor opts out
// Here I am checking user traits persisted to localStorage
const { user } = store.getState()
// user has optOut trait cancel action
if (user && user.traits.optOut) {
return next({
...action,
...{
abort: true,
reason: 'User opted out'
},
})
}
}
return next(finalAction)
}
export default optOutMiddleware
Plugins should follow this naming convention before being published to npm
analytics-plugin-{your-plugin-name}
E.g. An analytics plugin that does awesome-stuff should be named
npm install analytics-plugin-awesome-stuff
Then submit to the list above
During development you can turn on debug mode. This will connect redux dev tools for you to visually see the analytics events passing through your application.
[GIF]
import Analytics from 'analytics'
const analytics = Analytics({
app: 'my-app-name',
debug: true
})
Contributions are always welcome, no matter how large or small. Before contributing, please read the code of conduct.
FAQs
Lightweight analytics library for tracking events, page views, & identifying users. Works with any third party analytics provider via an extendable plugin system.
We found that analytics demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.