@analytics/core

v0.12.9

Lightweight analytics library for tracking events, page views, & identifying users. Works with any third party analytics provider via an extendable plugin system. For more information about how to use this package see README

Latest version published 2 months ago

License: MIT

NPM

GitHub

Package Health Score

89 / 100

security
No known security issues
popularity
Influential project
maintenance
Healthy
community
Active

Explore Similar Packages

Security

No known security issues

All security vulnerabilities belong to production dependencies of direct and indirect packages.

Security and license risk for significant versions

All Versions

Version				Vulnerabilities	License Risk
0.12.9	\|	02/2024	Popular	0 C 0 H 0 M 0 L	0 H 0 M 0 L
0.11.1	\|	03/2022		0 C 0 H 0 M 0 L	0 H 0 M 0 L
0.10.23	\|	02/2022		0 C 0 H 0 M 0 L	0 H 0 M 0 L
0.9.3	\|	01/2021		0 C 0 H 0 M 0 L	0 H 0 M 0 L
0.8.0	\|	12/2020		0 C 0 H 0 M 0 L	0 H 0 M 0 L

License

MIT

Security Policy

Is your project affected by vulnerabilities?

Scan your projects for vulnerabilities. Fix quickly with automated fixes. Get started with Snyk for free.

Get started free

Popularity

Influential project

Weekly Downloads (173,908)

GitHub Stars: 2.34K
Forks: 234
Contributors: 60

Direct Usage Popularity

The npm package @analytics/core receives a total of 173,908 downloads a week. As such, we scored @analytics/core popularity level to be Influential project.

Based on project statistics from the GitHub repository for the npm package @analytics/core, we found that it has been starred 2,338 times.

Downloads are calculated as moving averages for a period of the last 12 months, excluding weekends and known missing data points.

Community

Active

Readme.md: Yes
Contributing.md: Yes
Code of Conduct: Yes
Contributors: 60
Funding: Yes

With more than 10 contributors for the @analytics/core repository, this is possibly a sign for a growing and inviting community.

Embed Package Health Score Badge

Maintenance

Healthy

Commit Frequency

Open Issues: 76
Open PR: 24
Last Release: 2 months ago
Last Commit: 19 days ago

Further analysis of the maintenance status of @analytics/core based on released npm versions cadence, the repository activity, and other data points determined that its maintenance is Healthy.

We found that @analytics/core demonstrates a positive version release cadence with at least one new version released in the past 3 months.

As a healthy sign for on-going project maintenance, we found that the GitHub repository had at least 1 pull request or issue interacted with by the community.

Keep your project healthy

Check your package.json

Ensure all the packages you're using are healthy and well-maintained

Snyk Vulnerability Scanner

Get health score & security insights directly in your IDE

Package

Node.js Compatibility: not defined

Age: 4 years
Dependencies: 3 Direct
Versions: 42
Install Size: 3.57 MB
Dist-tags: 2
# of Files: 45
Maintainers: 1
TS Typings: Yes

@analytics/core has more than a single and default latest tag published for the npm package. This means, there may be other tags available for this package, such as next to indicate future releases, or stable to indicate stable releases.

Readme

Analytics Core

npm npm bundle size GitHub

A lightweight analytics abstraction library for tracking page views, custom events, & identify visitors.

Designed to work with any third-party analytics tool or your own backend.

Read the docs or view the live demo app

Click to expand

Features

[x] Extendable - Bring your own third-party tool & plugins
[x] Test & debug analytics integrations with time travel & offline mode
[x] Add functionality/modify tracking calls with baked in lifecycle hooks
[x] Isomorphic. Works in browser & on server
[x] Queues events to send when analytic libraries are loaded
[x] Conditionally load third party scripts
[x] Works offline
[x] TypeScript support

Why

Companies frequently change analytics requirements based on evolving needs. This results in a lot of complexity, maintenance, & extra code when adding/removing analytic services to a site or application.

This library aims to solves that with a simple pluggable abstraction layer.

how analytics works

Driving philosophy:

You should never be locked into an analytics tool
DX is paramount. Adding & removing analytic tools from your application should be easy
Respecting visitor privacy settings & allowing for opt-out mechanisms is crucial
A pluggable API makes adding new business requests easy

To add or remove an analytics provider, adjust the plugins you load into analytics during initialization.

Install

This module is distributed via npm, which is bundled with node and should be installed as one of your project's dependencies.

npm install analytics --save

Or as a script tag:

Usage

import Analytics from 'analytics'
import googleAnalytics from '@analytics/google-analytics'
import customerIo from '@analytics/customerio'

/* Initialize analytics */
const analytics = Analytics({
  app: 'my-app-name',
  version: 100,
  plugins: [
    googleAnalytics({
      trackingId: 'UA-121991291',
    }),
    customerIo({
      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'
})

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 googleAnalytics = require('@analytics/google-analytics')
const customerIo = require('@analytics/customerio')

const analytics = Analytics({
  app: 'my-app-name',
  version: 100,
  plugins: [
    googleAnalytics({
      trackingId: 'UA-121991291',
    }),
    customerIo({
      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'
})

Browser usage

When importing global analytics into your project from a CDN, the library exposes via a global _analytics variable.

Call _analytics.init to create an analytics instance.

Demo

See Analytics Demo for a site example.

API

The core analytics API is exposed once the library is initialized with configuration.

Typical usage:

Initialize with configuration
Export the analytics instance with third-party providers (Google Analytics, HubSpot, etc)
Use page, identify, track in your app
Plugin custom business logic

Configuration

Analytics library configuration

After the library is initialized with config, the core API is exposed & ready for use in the application.

Arguments

config object - analytics core config
[config.app] (optional) string - Name of site / app
[config.version] (optional) string - Version of your app
[config.debug] (optional) boolean - Should analytics run in debug mode
[config.plugins] (optional) Array.<AnalyticsPlugin> - Array of analytics plugins

Example

import Analytics from 'analytics'
import pluginABC from 'analytics-plugin-abc'
import pluginXYZ from 'analytics-plugin-xyz'

// initialize analytics
const analytics = Analytics({
  app: 'my-awesome-app',
  plugins: [
    pluginABC,
    pluginXYZ
  ]
})

analytics.identify

Identify a user. This will trigger identify calls in any installed plugins and will set user data in localStorage

Arguments

userId String - Unique ID of user
[traits] (optional) Object - Object of user traits
[options] (optional) Object - Options to pass to identify call
[callback] (optional) Function - Callback function after identify completes

Example

// Basic user id identify
analytics.identify('xyz-123')

// Identify with additional traits
analytics.identify('xyz-123', {
  name: 'steve',
  company: 'hello-clicky'
})

// Fire callback with 2nd or 3rd argument
analytics.identify('xyz-123', () =&gt; {
  console.log('do this after identify')
})

// Disable sending user data to specific analytic tools
analytics.identify('xyz-123', {}, {
  plugins: {
    // disable sending this identify call to segment
    segment: false
  }
})

// Send user data to only to specific analytic tools
analytics.identify('xyz-123', {}, {
  plugins: {
    // disable this specific identify in all plugins except customerio
    all: false,
    customerio: true
  }
})

analytics.track

Track an analytics event. This will trigger track calls in any installed plugins

Arguments

eventName String - Event name
[payload] (optional) Object - Event payload
[options] (optional) Object - Event options
[callback] (optional) Function - Callback to fire after tracking completes

Example

// Basic event tracking
analytics.track('buttonClicked')

// Event tracking with payload
analytics.track('itemPurchased', {
  price: 11,
  sku: '1234'
})

// Fire callback with 2nd or 3rd argument
analytics.track('newsletterSubscribed', () =&gt; {
  console.log('do this after track')
})

// Disable sending this event to specific analytic tools
analytics.track('cartAbandoned', {
  items: ['xyz', 'abc']
}, {
  plugins: {
    // disable track event for segment
    segment: false
  }
})

// Send event to only to specific analytic tools
analytics.track('customerIoOnlyEventExample', {
  price: 11,
  sku: '1234'
}, {
  plugins: {
    // disable this specific track call all plugins except customerio
    all: false,
    customerio: true
  }
})

analytics.page

Trigger page view. This will trigger page calls in any installed plugins

Arguments

[data] (optional) PageData - Page data overrides.
[options] (optional) Object - Page tracking options
[callback] (optional) Function - Callback to fire after page view call completes

Example

// Basic page tracking
analytics.page()

// Page tracking with page data overrides
analytics.page({
  url: 'https://google.com'
})

// Fire callback with 1st, 2nd or 3rd argument
analytics.page(() =&gt; {
  console.log('do this after page')
})

// Disable sending this pageview to specific analytic tools
analytics.page({}, {
  plugins: {
    // disable page tracking event for segment
    segment: false
  }
})

// Send pageview to only to specific analytic tools
analytics.page({}, {
  plugins: {
    // disable this specific page in all plugins except customerio
    all: false,
    customerio: true
  }
})

analytics.user

Get user data

Arguments

[key] (optional) 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')

analytics.reset

Clear all information about the visitor & reset analytic state.

Arguments

[callback] (optional) Function - Handler to run after reset

Example

// Reset current visitor
analytics.reset()

analytics.ready

Fire callback on analytics ready event

Arguments

callback Function - function to trigger when all providers have loaded

Example

analytics.ready((payload) =&gt; {
  console.log('all plugins have loaded or were skipped', payload);
})

analytics.on

Attach an event handler function for analytics lifecycle events.

Arguments

name String - Name of event to listen to
callback Function - function to fire on event

Example

// Fire function when 'track' calls happen
analytics.on('track', ({ payload }) =&gt; {
  console.log('track call just happened. Do stuff')
})

// Remove listener before it is called
const removeListener = analytics.on('track', ({ payload }) =&gt; {
  console.log('This will never get called')
})

// cleanup .on listener
removeListener()

analytics.once

Attach a handler function to an event and only trigger it once.

Arguments

name String - Name of event to listen to
callback Function - function to fire on event

Example

// Fire function only once per 'track'
analytics.once('track', ({ payload }) =&gt; {
  console.log('This is only triggered once when analytics.track() fires')
})

// Remove listener before it is called
const listener = analytics.once('track', ({ payload }) =&gt; {
  console.log('This will never get called b/c listener() is called')
})

// cleanup .once listener before it fires
listener()

analytics.getState

Get data about user, activity, or context. Access sub-keys of state with dot.prop syntax.

Arguments

[key] (optional) string - dot.prop.path value of state

Example

// Get the current state of analytics
analytics.getState()

// Get a subpath of state
analytics.getState('context.offline')

analytics.storage

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')

analytics.storage.getItem

Get value from storage

Arguments

key String - storage key
[options] (optional) Object - storage options

Example

analytics.storage.getItem('storage_key')

analytics.storage.setItem

Set storage value

Arguments

key String - storage key
value any - storage value
[options] (optional) Object - storage options

Example

analytics.storage.setItem('storage_key', 'value')

analytics.storage.removeItem

Remove storage value

Arguments

key String - storage key
[options] (optional) Object - storage options

Example

analytics.storage.removeItem('storage_key')

analytics.plugins

Async Management methods for plugins.

This is also where custom methods are loaded into the instance.

Example

// Enable a plugin by namespace
analytics.plugins.enable('keenio')

// Disable a plugin by namespace
analytics.plugins.disable('google-analytics')

analytics.plugins.enable

Enable analytics plugin

Arguments

plugins string|Array.<string> - name of plugins(s) to disable
[callback] (optional) Function - callback after enable runs

Example

analytics.plugins.enable('google-analytics').then(() =&gt; {
  console.log('do stuff')
})

// Enable multiple plugins at once
analytics.plugins.enable(['google-analytics', 'segment']).then(() =&gt; {
  console.log('do stuff')
})

analytics.plugins.disable

Disable analytics plugin

Arguments

plugins string|Array.<string> - name of integration(s) to disable
callback Function - callback after disable runs

Example

analytics.plugins.disable('google').then(() =&gt; {
  console.log('do stuff')
})

analytics.plugins.disable(['google', 'segment']).then(() =&gt; {
  console.log('do stuff')
})

Events

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 }) =&gt; {
  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.plugins.enable()' is called
`disablePlugin`	Fires when 'analytics.plugins.disable()' 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.

Analytic plugins

The analytics has a robust plugin system. Here is a list of currently available plugins:

Plugin	Stats	Version
@analytics/activity-utils User activity listener utilities		0.1.16
@analytics/amplitude Amplitude integration for 'analytics' module		0.1.3
@analytics/aws-pinpoint AWS Pinpoint integration for 'analytics' module		0.7.11
@analytics/cookie-utils Tiny cookie utility library		0.2.12
@analytics/core Lightweight analytics library for tracking events, page views, & identifying users. Works with any third party analytics provider via an extendable plugin system.		0.12.7
@analytics/countly Countly plugin for 'analytics' module		0.21.12
@analytics/crazy-egg Crazy Egg integration for 'analytics' module		0.1.2
@analytics/custify Custify integration for 'analytics' module for browser & node		0.0.2
@analytics/customerio Customer.io integration for 'analytics' module		0.2.2
@analytics/form-utils Form utility library for managing HTML form submissions & values		0.3.13
@analytics/fullstory Unofficial FullStory plugin for 'analytics' module		0.2.6
@analytics/global-storage-utils Tiny global storage utility library		0.1.7
@analytics/google-analytics Google analytics v4 plugin for 'analytics' module		1.0.7
@analytics/google-tag-manager Google tag manager plugin for 'analytics' module		0.5.5
@analytics/google-analytics-v3 Google analytics v3 plugin for 'analytics' module		0.6.1
@analytics/gosquared GoSquared integration for 'analytics' module		0.1.3
@analytics/hubspot HubSpot plugin for 'analytics' module		0.5.1
@analytics/intercom Intercom integration for 'analytics' module for browser & node		1.0.2
@analytics/listener-utils Backward compatible event listener library for attaching & detaching event handlers		0.4.0
@analytics/localstorage-utils Tiny LocalStorage utility library		0.1.10
@analytics/mixpanel Mixpanel plugin for 'analytics' module		0.4.0
@analytics/original-source-plugin Save original referral source of visitor plugin for 'analytics' pkg		1.0.11
@analytics/ownstats Ownstats integration for 'analytics' module for browser & node		0.1.2
@analytics/perfumejs Send browser performance metrics to third-party analytics providers		0.2.1
@analytics/queue-utils Dependency free queue processor		0.1.2
@analytics/redact-utils Utility library for redacting event data		0.1.3
@analytics/remote-storage-utils Storage utilities for cross domain localStorage access, with permissions		0.4.20
@analytics/router-utils Route change utilities for single page apps		0.1.1
@analytics/scroll-utils Scroll utility library to fire events on scroll		0.1.22
@analytics/segment Segment integration for 'analytics' module for browser & node		2.1.0
@analytics/session-storage-utils Tiny SessionStorage utility library		0.0.7
@analytics/session-utils Tiny session utility library		0.1.19
@analytics/simple-analytics Simple analytics plugin for 'analytics' module for browser		0.4.0
@analytics/snowplow Snowplow integration for 'analytics' module for browser & node		0.3.3
@analytics/storage-utils Storage utility with fallbacks		0.4.2
@analytics/type-utils Tiny runtime type checking utils		0.6.2
@analytics/url-utils Url utils		0.2.3
@analytics/visitor-source Get visitor source		0.0.7
analytics-cli CLI for `analytics` pkg		0.0.5
analytics-plugin-do-not-track Disable tracking for opted out visitors plugin for 'analytics' module		0.1.5
analytics-plugin-event-validation Event validation plugin for analytics		0.1.2
gatsby-plugin-analytics Easily add analytics to your Gatsby site		0.2.0
analytics-plugin-lifecycle-example Example plugin with lifecycle methods for 'analytics' module		0.1.2
analytics-plugin-tab-events Expose tab visibility events plugin for 'analytics' module		0.2.1
use-analytics Analytics hooks for React		1.1.0
analytics-util-params Url Parameter helper functions		0.1.2
analytics-utils Analytics utility functions used by 'analytics' module		1.0.12
analytics-plugin-window-events Expose window events plugin for 'analytics' module		0.0.7

Community Plugins

Below are plugins created outside of this repo:

ActiveCampaign Adds Analytics support for ActiveCampaign
analytics-fetch Integration with the browser's fetch API for analytics
Conscia Adds Analytics support for conscia.ai
Facebook tracking pixel Send data to Facebook Tracking pixel
Indicative Adds Analytics support for Indicative
LinkedIn Pixel Adds Analytics support for Linkedin tracking pixel
Logrocket Adds Analytics support for LogRocket
Planhat Adds Analytics support for Planhat
Plausible Adds Analytics support for Plausible
PostHog Adds Analytics support for PostHog by @metro-fs
PostHog Adds Analytics support for PostHog by deevus
ProfitWell Adds Analytics support for ProfitWell
Reddit Pixel Adds Analytics support for Reddit Pixel
RudderStack Adds Analytics support for RudderStack
Splitbee Adds Analytics support for Splitbee
Tapfiliate Adds Analytics support for Tapfiliate
Yandex Send data to Yandex metrica
Add a plugin link

Additional examples

Creating analytics plugins

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 name */
    name: 'my-example-plugin',
    /* Everything else below this is optional depending on your plugin requirements */
    config: {
      whatEver: userConfig.whatEver,
      elseYouNeed: userConfig.elseYouNeed
    },
    initialize: ({ config }) =&gt; {
      // load provider script to page
    },
    page: ({ payload }) =&gt; {
      // call provider specific page tracking
    },
    track: ({ payload }) =&gt; {
      // call provider specific event tracking
    },
    identify: ({ payload }) =&gt; {
      // call provider specific user identify method
    },
    loaded: () =&gt; {
      // return boolean so analytics knows when it can send data to third-party
      return !!window.myPluginLoaded
    }
  }
}

name 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
  ]
})

React to any event

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 {
    /* Name is a required field for plugins */
    name: 'my-plugin',
    /* Bootstrap runs when analytics starts */
    bootstrap: ({ payload, config, instance }) =&gt; {
      // Do whatever on `bootstrap` event
    },
    pageStart: ({ payload, config, instance }) =&gt; {
      // Fire custom logic before analytics.page() calls
    },
    pageEnd: ({ payload, config, instance }) =&gt; {
      // Fire custom logic after analytics.page() calls
    },
    trackStart: ({ payload, config, instance }) =&gt; {
      // Fire custom logic before analytics.track() calls
    },
    'track:customerio': ({ payload, config, instance }) =&gt; {
      // Fire custom logic before customer.io plugin runs.
      // Here you can customize the data sent to individual analytics providers
    },
    trackEnd: ({ payload, config, instance }) =&gt; {
      // 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/customerio'
import myPlugin from './plugin.js'

const analytics = Analytics({
  app: 'my-app-name',
  plugins: [
    // include myPlugin
    myPlugin(),
    customerIoPlugin({
      trackingId: '1234'
    })
    ...otherPlugins
  ]
})

Custom methods

Analytics plugins can provide their own custom functionality via the methods key.

import Analytics from 'analytics'

// Example plugin with custom methods
const pluginOne = {
  name: 'one',
  // ... page, track, etc
  // Custom functions to expose to analytics instance
  methods: {
    myCustomThing(one, two, three) {
      const analyticsInstance = this.instance
      console.log('Use full analytics instance', analyticsInstance)
    },
    otherCustomThing: (one, two, ...args) =&gt; {
      // Arrow functions break this.instance context.
      // The instance is instead injected as last arg
      const analyticsInstance = args[args.length - 1]
      console.log('Use full analytics instance', analyticsInstance)
    },
    // Async function examples
    async fireCustomThing(one, two, three) {
      const { track } = this.instance
      track('customThing')
      return 'data'
    },
    triggerSpecial: async (argOne, argTwo, ...args) =&gt; {
      // Arrow functions break this.instance context.
      // The instance is instead injected as last arg
      const analyticsInstance = args[args.length - 1]
      return argOne + argTwo
    }
  }
}

// Example plugin with custom methods
const pluginTwo = {
  name: 'two',
  page: () =&gt; { console.log('page view fired') }
  // Custom functions to expose to analytics instance
  methods: {
    cookieBanner(one, two, three) {
      const analyticsInstance = this.instance
      console.log('Use full analytics instance', analyticsInstance)
      const cookieSettings = analyticsInstance.storage.getItem('preferences-set')
      if (!cookieSettings) {
        // Show cookie settings
      }
    },
  }
}

// Initialize analytics instance with plugins
const analytics = Analytics({
  app: 'your-app-name',
  plugins: [
    pluginOne,
    pluginTwo
  ]
})

// Using custom methods in your code
analytics.plugins.one.myCustomThing()
analytics.plugins.two.cookieBanner()

Plugin Naming Conventions

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

Debugging analytics

During development, you can turn on debug mode. This will connect the dev tools for you to see the analytics events passing through your application visually.

analytics-debug-tools

import Analytics from 'analytics'

const analytics = Analytics({
  app: 'my-app',
  debug: true
})

TypeScript support

Types for analytics and plugins are generated from JSDoc blocks in the code base via the tsd-jsdoc package.

We are always looking to improve type support & improve the DX of users. If you see something that can be improved let us know in an issue!

Contributing

Contributions are always welcome, no matter how large or small. Before contributing, please read the code of conduct.

Setup & Install dependencies

Clone the repo and run

$ git clone https://github.com/davidwells/analytics
$ cd analytics
$ npm install &amp;&amp; npm run setup

The above command will set up all the packages and their dependencies.

Development

You can watch and rebuild packages with the npm run watch command.

npm run watch

While watch mode is activated, you can work against the demo site in examples to test out your changes on a live application.

@analytics/core dependencies

@analytics/global-storage-utils @analytics/type-utils analytics-utils

@analytics/core development dependencies

@babel/core @babel/plugin-proposal-class-properties @babel/plugin-transform-runtime @babel/preset-env @babel/register @babel/runtime ava gen-esm-wrapper microbundle mkdirp npm-run-all rimraf sinon

FAQs

What is @analytics/core?

Lightweight analytics library for tracking events, page views, & identifying users. Works with any third party anal... Visit Snyk Advisor to see a full health score report for @analytics/core, including popularity, security, maintenance & community analysis.

Is @analytics/core popular?

The npm package @analytics/core receives a total of 173,908 weekly downloads. As such, @analytics/core popularity was classified as an influential project. Visit the popularity section on Snyk Advisor to see the full health analysis.

Is @analytics/core well maintained?

We found that @analytics/core demonstrated a healthy version release cadence and project activity. It has a community of 60 open source contributors collaborating on the project. See the full package health analysis to learn more about the package maintenance status.

Is @analytics/core safe to use?

The npm package @analytics/core was scanned for known vulnerabilities and missing license, and no issues were found. Thus the package was deemed as safe to use. See the full health analysis review.

Last updated on 21 April-2024, at 12:47 (UTC).

Build a secure application checklist

Select a recommended open source package

Minimize your risk by selecting secure & well maintained open source packages

DONE

Scan your app for vulnerabilities

Scan your application to find vulnerabilities in your: source code, open source dependencies, containers and configuration files

SCAN NOW

Fix identified vulnerabilities

Easily fix your code by leveraging automatically generated PRs

AUTO FIX

Monitor for new issues

New vulnerabilities are discovered every day. Get notified if your application is affected

MONITOR APP

Package Health Score

Explore Similar Packages

Security and license risk for significant versions

Is your project affected by vulnerabilities?

Weekly Downloads (173,908)

Direct Usage Popularity

Embed Package Health Score Badge

Commit Frequency

Keep your project healthy

Check your package.json

Snyk Vulnerability Scanner

Readme

Analytics Core

Table of Contents

Features

Why

Install

Usage

Demo

API

Configuration

analytics.identify

analytics.track

analytics.page

analytics.user

analytics.reset

analytics.ready

analytics.on

analytics.once

analytics.getState

analytics.storage

analytics.storage.getItem

analytics.storage.setItem

analytics.storage.removeItem

analytics.plugins

analytics.plugins.enable

analytics.plugins.disable

Events

Analytic plugins

Community Plugins

Creating analytics plugins

React to any event

Custom methods

Plugin Naming Conventions

Debugging analytics

TypeScript support

Contributing

Setup & Install dependencies

Development

@analytics/core dependencies

@analytics/core development dependencies

FAQs

What is @analytics/core?

Is @analytics/core popular?

Is @analytics/core well maintained?

Is @analytics/core safe to use?

Build a secure application checklist

Select a recommended open source package

Scan your app for vulnerabilities

Source Code

Open Source

Container

Config

Fix identified vulnerabilities

Monitor for new issues