@getcircuit/analytics
A thin analytics abstraction layer for Circuit's applications. It implements a basic plugin system for integrating with different analytics services.
Usage
- First things first, initialize the abstraction layer with the needed plugins:
import {
Analytics,
googleAnalytics,
facebookPixel,
} from '@getcircuit/analytics'
export const analytics = Analytics({
env: process.env.NODE_ENV,
debug: process.env.NODE_ENV === 'development',
dryRun: 'production',
plugins: [
googleAnalytics({
trackingId: 'UA-XXXXXX-X',
}),
facebookPixel({
pixelId: 'xxxxxxx',
}),
],
explicitUse: {
event: [...],
pageview: [...],
...,
}
})
- Track actions, users and errors
After initializing, you can use the abstraction layer to send:
- Events:
analytics.event(...)
- Pageviews:
analytics.pageview(...)
- User identification: :
analytics.identify(...)
- User anonymization:
analytics.anonymize(...)
- Info logs:
analytics.info(...)
- Warning logs:
analytics.warn(...)
- Error logs:
analytics.error(...)
Only plugins that implement the hook will be executed. The load
of each plugin is deferred until one of its hooks are executed, which means that any analytics code will only be added to the DOM when sending a tracking request.
Plugin
A plugin is just an object with a specific set of methods, which we call 'hooks' and a name
property. The only mandatory hook is the load()
, responsible for adding the service script to the DOM.
{
name: string
load: () => MaybePromise
unload?: () => MaybePromise
pageview?: (opts: PageviewOptions) => MaybePromise
event?: (opts: TrackEventOptions) => MaybePromise
identify?: (opts: IdentifyOptions) => MaybePromise
anonymize?: () => MaybePromise
info?: (opts: TraceOptions) => MaybePromise
warn?: (opts: TraceOptions) => MaybePromise
error?: (opts: TraceOptions) => MaybePromise
}
Apart from load
and unload
, each hook correspond to a method in the abstraction layer.
Available plugins
- Amplitude
- Autopilot
- Bugsnag
- Facebook Pixel
- Fullstory
- Google Analytics
- Helpscout
- Intercom
- UTM Cookie
- Used for storing UTM data in a cookie.
Hooks
Every hook has access to a this
object which contains:
type PluginContext = {
config: {
env: string
appName: string
appVersion: string
debug: boolean
}
assertKeys: (object, requiredKeys) => void
assertValues: (objectOfValues) => void
}