@exodus/analytics

Exodus analytics

A base class encapsulating analytics integration.

API Reference

Property name	Description
setAnonymousId	Use this to set a temporary id, mostly used to track onboarding events
setUserId	Use this to set the permanent user id, i.e. the seed derived id fetched from analyticsUserIdAtom
flush	Use this to send persisted events to segment. Events that are tracked before setPermanentUserId is set will need to be flushed
getAnonymousId	Gets the anonymousId associated with the tracker. This is a UUID until setPermanentUserId is called with the userId
track	Use this method to send events to segment. If setPermanentUserId has not been called, you must call track({ force: true }). To throttle tracked events, use track({ sample }) with sample ranging from 0-1, e.g. track({ sample: 0.2 }) will pass through 20% of events
setUserTraits	Used to set global "traits". Should be used sparingly -- on seed import or seed create for example.
setDefaultEventProperties	Pretty much as it sounds. This sets persistent properties to be sent with every call to segment via track
trackInstall	sets a persisted event that can be sent with flush postinstall

Usage

import createStorage from '@exodus/storage-memory' // use the relevant platform-specific implementation
import analyticsDefinition from '@exodus/analytics/module'
import Tracker from '@exodus/segment-metrics'

const analytics = analyticsDefinition.factory({
  storage: storage.namespace('analytics'),
  shareActivityAtom,
  tracker: new Tracker({ writeKey: segmentApiKey }),
  // optional
  config: {
    installEventReportingUrl,
  },
  logger,
})

// before onboarding, while not mandatory, it's recommended to set an annonymousId so all
// events triggered until we have can derive real userId from seed can be linked together
const anonymousId = '5c8d5e90-1ddb-4bdc-b428-a03ac2358c7f'
analytics.setAnonymousId(anonymousId)

// if we want all events to have a common set of properties, we can require their presence
analytics.requireDefaultEventProperties(['build', 'version'])

// now we can start tracking events
// using force: true, you can send the event right away associated w/ the anonymousId
// force: false (default) will simply persist the event until you call .flush()
analytics.track({ event: 'PersistedEvent' })
analytics.track({ event: 'UrgentEvent', force: true })

// throw out ~70% of events
analytics.track({ event: 'ThrottledEvent', sample: 0.3 })

// after we have access to a seed, analyticsUserIdAtom should hold a unique userId value
const userId = await analyticsUserIdAtom.get()
analytics.setUserId(userId)

// link anonymousId and userId together, done only once on wallet creation or import
analytics.linkUserIds({ userId, annonymousId })

// flush persisted events. Note this won't flush them right away, will wait for required properties are present
analytics.flush()

// set default properties
analytics.setDefaultEventProperties({ build: 'genesis', version: '1.0.0' })

// events will flow directly to segment now with real user id
analytics.track({ event: 'OtherEvent' })

Constructor Options

Property name	Required	Description
tracker	yes	A Tracker class instance.
storage	yes	An object implementing the Storage interface (see below). Needed if you need to persist events (e.g. when a consumer application can be temporarily locked).
shareActivityAtom	yes	An atom returning a boolean value indicating if a consumer application is ready to send events.
config	no	Static configuration options
config.installEventReportingUrl	no	Url to which to post app install events

type SerializedEvent = 'string'

interface Storage {
  set: (key: string, events: SerializedEvent[]) => Promise<undefined>
  get: (key: string) => Promise<SerializedEvent[]>
}