@azfive/capture

Capture product-analytics events into AzFive from the browser or Node — a batteries-included analytics SDK: anonymous-id persistence, identify/reset, super properties, batching with sendBeacon on unload, and autocapture (az.page_view/az.page_leave + DOM clicks).

Install / build

npm install      # in this directory
npm run build    # emits dist/ (ES + UMD + .d.ts)
npm test         # vitest (jsdom)

This is a standalone package (not part of the app's npm workspace), mirroring sdk/ (@azfive/embed).

Browser quickstart

Create a public ingest token in AzFive → Settings → API Keys → Public Ingest Tokens (scoped to your site's origins). It's safe to ship in page source.

import { init, azfive } from '@azfive/capture';

init('azfive_pub_…', { host: 'https://analytics.example.com', project: 'web' });

azfive.capture('signed_up', { plan: 'pro' });
azfive.identify('[email protected]', { plan: 'pro' });   // merges the anon session

// on logout:
await azfive.flush();
azfive.reset();

Autocapture (az.page_view, az.page_leave, DOM az.interaction clicks) is on by default. Mark sensitive elements with data-vz-no-capture (or .vz-no-capture); password/hidden inputs are never captured. Disable per-feature:

init(token, { autocapture: false, captureClicks: false });

React

The SDK is framework-agnostic — initialize a singleton once and import it anywhere:

// analytics.ts
import { createClient } from '@azfive/capture';
export const analytics = createClient('azfive_pub_…', { host: 'https://analytics.example.com' });

// any component
import { analytics } from './analytics';
analytics.capture('clicked_cta');

Node (server-side)

Use a secret events:write API key and supply the distinct_id yourself; no persistence/autocapture runs.

import { createClient } from '@azfive/capture';

const azfive = createClient('unused', { host: 'https://analytics.example.com', secretKey: 'azfive_…' });
azfive.capture('invoice_paid', { distinct_id: 'user-42', amount: 99 });
await azfive.flush();

API

init / createClient · capture · identify · alias · reset · getDistinctId · register / register_once / unregister (super properties) · people.set / people.set_once · opt_in_capturing / opt_out_capturing / has_opted_out_capturing · flush · destroy.

See docs/events.md for the end-to-end events architecture.