Quickstart

Create a workspace

A workspace is an isolated event stream with its own write key and destinations. Use one per product or brand — and a separate one for staging, since a workspace is the only real boundary between environments.

You’ll be asked for a name and your website. That’s it.

Copy your write key

Find it under Settings → API keys. It looks like wk_live_xxxxxxxxxxxx.

Write keys can only ingest events — they can’t read your data or change settings — so they’re safe to ship in browser code.

Install the SDK

$
npm install @pivolio/browser

Using React or Next.js? Install @pivolio/react or @pivolio/next instead — they wrap the same engine in a provider.

Initialize and track

1
import { init, page, track } from '@pivolio/browser';
2
3
init({
4
  writeKey: 'wk_live_xxxxxxxxxxxx',
5
  apiUrl: 'https://api.pivolio.com',
6
});
7
8
page();

Now track something. Note that event properties are nested under properties — this is the single most common mistake:

1
track('order_completed', {
2
  properties: { order_id: 'ord_123', revenue: 99.5, currency: 'USD' },
3
});

For commerce events, prefer the helpers. They map their arguments onto the exact property names the backend reads for revenue and deduplication:

1
import { trackPurchase } from '@pivolio/browser';
2
3
trackPurchase({ value: 99.5, currency: 'USD', orderId: 'ord_123' });

Identify your customers

Tie anonymous activity to a known person. Everything that visitor did before signing in is retroactively linked to them:

1
import { identify } from '@pivolio/browser';
2
3
identify({ user_id: 'user_456', email: 'jane@acme.com' });

Send raw email and phone — Pivolio normalizes and hashes them server-side, so every destination receives byte-identical digests. Hashing them yourself is the fastest way to quietly destroy your match rates.

Verify the event arrived

Open the Live Debugger in the dashboard. Events appear within a couple of seconds, showing which person they resolved to and how each destination handled them.

Connect a destination

Go to Destinations and connect one of Meta, Google Ads, TikTok or Reddit. Each has a short setup guide: