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 pluggable analytics library designed to work with any third party analytics tool.
Connect with your favorite analytic providers, trigger custom logic based on user activity, or easily provide opt out mechanisms for visitors who wish to turn off analytics entirely.
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 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'
const analytics = Analytics({
app: 'my-app-name',
version: 100,
plugins: [
googleAnalyticsPlugin({
trackingId: 'UA-121991291',
}),
customerIOPlugin({
siteId: '123-xyz'
})
]
})
// Fire a page view
analytics.page()
// Fire event tracking
analytics.track('userPurchase', {
price: 20
})
// Identify a visitor
analytics.identify('user-id-xyz', {
firstName: 'bill',
lastName: 'murray',
email: 'da-coolest@aol.com'
})
//...
const { analytics } = require('analytics')
const analytics = Analytics({
app: 'my-app-name',
version: 100,
plugins: [
googleAnalyticsPlugin({
trackingId: 'UA-121991291',
}),
customerIOPlugin({
siteId: '123-xyz'
})
]
})
// Fire a page view
analytics.page()
<script src="https://unpkg.com/analytics/dist/analytics.min.js"></script>
<script>
const Analytics = analytics({
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.
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 indentify callFunction - Optional callback function after identify completesExample
identify('xyz-123', {
name: 'steve',
company: 'hello-clicky'
})
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
analytics.track('buttonClick')
Trigger page view. This will trigger page calls in any installed plugins
Arguments
String - (optional) page dataObject - Event optionsFunction - Callback to fire after page view call completesExample
analytics.page()
Get data about user, activity, or context. You can access sub-keys of state with dot.prop syntax.
Arguments
String - (optional) dotprop sub value of stateExample
// Get the current state of analytics
analytics.getState()
// Get a subpath of state
analytics.getState('context.offline')
Clear all information about the visitor & reset analytic state.
Arguments
Function - Handler to run after resetEmit events for other plugins or middleware to react to.
Arguments
Object [description]Storage utilities for persisting data. These methods will allow you to save data in localStorage, cookies, or to the window.
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')
Get user data
Arguments
String - dot.prop subpath of user dataExample
// 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')
Fire callback on analytics ready event
Arguments
Function - function to trigger when all providers have loadedExample
analytics.ready((action, instance) => {
console.log('all plugins have loaded')
})
Attach an event handler function for one or more events to the selected elements.
Arguments
String - Name of event to listen toFunction - function to fire on eventExample
analytics.on('track', ({ action, instance }) => {
console.log('track call just happened. Do stuff')
})
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
analytics.once('track', (action, instance) => {
console.log('This will only triggered once')
})
Enable analytics plugin
Arguments
String|Array - name of integration(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'])
Load registered analytic providers.
Arguments
String - integration namespaceExample
analytics.loadPlugin('segment')
Events exposed by core analytics library and all loaded plugins
The analytics has a robust plugin system. Here is a list of currently available plugins:
The library is designed to work with any third party analytics tool.
Plugins are just plain javascript objects that expose methods for analytics core to register and call.
Here is a quick example of a plugin. This is a 'vanilla' plugin example for connecting a third party analytics tool
// vanilla-example.js
export default function googleAnalytics(userConfig) {
// return object for analytics to use
return {
// All plugins require a namespace
NAMESPACE: 'google-analytics',
config: {
whatEver: userConfig.fooBar,
googleAnalyticsId: userConfig.id
},
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.gaplugins
}
}
}
To use a plugin, import it and pass it into the plugins array when you bootstrap analytics.
import Analytics from 'analytics'
import vanillaExample from './vanilla-example.js'
const analytics = Analytics({
app: 'my-app-name',
plugins: [
vanillaExample({ id: 'xyz-123' }),
...otherPlugins
]
})
Plugins can react to any event flowing through analytics.
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.
// plugin.js
export default function myPlugin(userConfig) {
return {
NAMESPACE: 'my-plugin',
bootstrap: ({ payload, config, instance }) => {
// Do whatever on `bootstrap`
},
pageStart: ({ payload, config, instance }) => {
// Fire custom logic before .page calls
},
pageEnd: ({ payload, config, instance }) => {
// Fire custom logic after .page calls
},
trackStart: ({ payload, config, instance }) => {
// Fire custom logic before .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 .track calls
},
...
}
}
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: [
myPlugin(),
customerIoPlugin({
trackingId: '1234'
})
...otherPlugins
]
})
Alternatively, you can also add whatever middleware functionality you'd like from the redux ecosystem.
// logger-plugin.js redux middleware
const logger = store => next => action => {
if (action.type) {
console.log(`>> dispatching ${action.type}`, JSON.stringify(action))
}
let result = next(action)
return result
}
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 a naming convention before being published to NPM
analytics-plugin-{your-plugin-name}
npm install analytics-plugin-awesome-thing
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.
The npm package analytics receives a total of 137,920 weekly downloads. As such, analytics popularity was classified as popular.
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.