repository·master·Indexed 25 days ago
https://github.com/davidwells/analyticsA lightweight analytics abstraction library for tracking page views, custom events, and identifying visitors. It provides a pluggable layer that allows developers to switch or add third-party analytics tools, such as Amplitude and Google Analytics, without changing application code. It includes support for Next.js App Router, React, Vue, Preact, and Vanilla JS, as well as a companion CLI tool.
@analytics/type-utils is a tiny (approx. 2.3kb), tree-shakable utility library designed for runtime type checking. It provides 60 re-usable functions and environment flags to help detect the current execution environment (e.g., browser, node, deno) and runtime state (e.g., production, staging, development).@analytics/type-utils library provides a collection of approximately 60 re-usable functions and environment flags designed for runtime type checking. It is optimized for small bundle sizes (approx. 2.3kb) and is tree-shakable.analytics-cli is a command-line interface designed for use with the analytics package. It allows you to interact with your analytics configuration and data via the terminal.analytics library is designed to work in both browsers and server-side JavaScript runtimes.Install the @analytics/url-utils package from npm to use its URL manipulation and parsing utilities.
npm install @analytics/url-utilsInstall the @analytics/scroll-utils library from npm to use its utility functions for handling scroll events.
npm install @analytics/scroll-utilsTo track the initial traffic source and the first page visited by a user, install the analytics core package and the analytics-plugin-original-source plugin via npm.
npm install analytics
npm install analytics-plugin-original-sourceInstall the @analytics/form-utils library from npm to manage HTML form data and utility functions.
npm install @analytics/form-utilsUse analytics-plugin-event-validation to ensure tracking events passed to analytics conform to a specific naming convention: context:objectName_actionName. This helps maintain clean analytics data by enforcing a pattern of Context => Object => Action.
To use it, include the plugin in your Analytics configuration and define the context (the namespace of your application) and the list of allowed objects.
import Analytics from 'analytics'
import eventValidation from 'analytics-plugin-event-validation'
import customerIOPlugin from 'analytics-plugin-customerio'
const analytics = Analytics({
app: 'awesomesauce',
plugins: [
eventValidation({
// Namespace of current application
context: 'app',
// Allowed objects
objects: [
'sites', // example app:sites_cdConfigured
'user', // example app:user_signup
'widget' // example app:widget_created
]
}),
customerIOPlugin({
siteId: '123-xyz'
}),
]
})
// Event names must now conform to this format:
analytics.track('app:sites_whatever')
analytics.track('app:user_action')
analytics.track('app:widget_deleted')Initialize the analytics instance by passing the awsPinpointPlugin into the plugins array. You must provide a pinpointAppId and a getCredentials function that returns AWS Cognito credentials.
import Analytics from 'analytics'
import awsPinpointPlugin from '@analytics/aws-pinpoint'
const analytics = Analytics({
app: 'awesome-app',
plugins: [
awsPinpointPlugin({
pinpointAppId: '938bebb1ae954e123133213160f2b3be4',
getCredentials: () => Auth.currentCredentials()
})
]
})To use multiple Google Analytics instances in a single application, use the instanceName configuration field and override the default plugin name to avoid namespace collisions. This allows tracking data to flow into multiple GA accounts simultaneously.
import Analytics from 'analytics'
import googleAnalytics from '@analytics/google-analytics-v3'
// Normal google analytics instance
const instanceOne = googleAnalytics({
trackingId: '123-xyz',
})
// Second google analytics instance with override for 'name' field of the plugin
const instanceTwo = {
...googleAnalytics({
trackingId: '567-abc',
instanceName: 'two'
}),
name: 'google-analytics-two'
}
const analytics = Analytics({
app: 'awesome-app',
plugins: [
instanceOne,
instanceTwo
]
})Use analytics.reset() to clear out saved userId, anonymousId, user traits, and any third-party cookies or local storage values set by active analytics plugins. This is typically used when a user logs in to a different account to ensure analytics starts with a clean slate and a new anonymous user ID.
import Analytics from 'analytics'
import googleAnalyticsPlugin from '@analytics/google-analytics'
/* Initialize analytics */
const analytics = Analytics({
app: 'my-app-name',
version: 100,
plugins: [
googleAnalyticsPlugin({
trackingId: 'UA-121991291',
})
]
})
// Call analytics.reset to reset user Id & traits
analytics.reset()