Web SDKv2.xMIT License

TypeScript Browser SDK

@acai/analytics-browser is the modern browser SDK with first-class TypeScript support, a plugin architecture, and optional autocapture.

Installation

Shell

npm install @acai/analytics-browser

Initialise

TypeScript

import * as acai from '@acai/analytics-browser'

acai.init('YOUR_API_KEY', {
  serverUrl: 'https://events.yourdomain.com/2/httpapi',
})

Pass a user ID at init or later via setUserId:

TypeScript

acai.init('YOUR_API_KEY', {
  serverUrl: 'https://events.yourdomain.com/2/httpapi',
  userId:    'user_abc123',
})

Track events

TypeScript

acai.track('Button Clicked')

acai.track('Purchase Completed', {
  product_id: 'prod_123',
  price:       49.99,
  currency:    'USD',
})

// Force flush the queue
await acai.flush().promise

Identify users

TypeScript

import { Identify } from '@acai/analytics-browser'

acai.setUserId('user_abc123')

const identifyObj = new Identify()
identifyObj.set('plan', 'pro')
identifyObj.setOnce('signup_date', '2024-01-15')
identifyObj.add('session_count', 1)
identifyObj.append('tags', 'power-user')
identifyObj.unset('trial_active')

acai.identify(identifyObj)

acai.setGroup('company', 'Acme Corp')

Plugins

Autocapture

TypeScript

import { autocapturePlugin } from '@acai/plugin-autocapture-browser'

acai.init('YOUR_API_KEY', { serverUrl: '...' })
acai.add(autocapturePlugin())

Page view tracking

TypeScript

import { pageViewTrackingPlugin } from '@acai/plugin-page-view-tracking-browser'

acai.add(pageViewTrackingPlugin())

Web attribution (UTM / referrer)

TypeScript

import { webAttributionPlugin } from '@acai/plugin-web-attribution-browser'

acai.add(webAttributionPlugin())

Custom enrichment plugin

TypeScript

const myPlugin = {
  name: 'my-enrichment',
  type: 'enrichment',
  execute: async (event) => {
    event.event_properties = {
      ...event.event_properties,
      app_version: '2.1.0',
    }
    return event
  },
}

acai.add(myPlugin)

Config reference

Option	Type	Description
`serverUrl`	string	Full collector URL: `https://events.yourdomain.com/2/httpapi`
`userId`	string	Pre-set authenticated user ID.
`deviceId`	string	Override the auto-generated device ID.
`optOut`	boolean	Disable all event collection.
`flushQueueSize`	number	Events per batch before an automatic flush.
`flushIntervalMillis`	number	Max wait before flushing the queue (ms).
`logLevel`	LogLevel	`None` · `Error` · `Warn` · `Verbose`
`autocapture`	object	Fine-grained autocapture: `{ sessions, pageViews, networkTracking }`
`serverZone`	string	`US` or `EU`. Ignored when `serverUrl` is set.