> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivolio.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivolio.com/_mcp/server.

# Quickstart

This walks the same path the dashboard's **Get started** checklist does. Budget
about ten minutes.

#### 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

```bash
npm install @pivolio/browser
```

#### Script tag

The IIFE build exposes a global named `Pivolio`, and drains any commands
you queued on `window.pivolio` before it loaded:

```html
<script>
  window.pivolio = window.pivolio || [];
  pivolio.push(['init', {
    writeKey: 'wk_live_xxxxxxxxxxxx',
    apiUrl: 'https://api.pivolio.com',
  }]);
  pivolio.push(['page']);
</script>
<script async src="https://unpkg.com/@pivolio/browser@1/dist/browser.browser.js"></script>
```

Using React or Next.js? Install [`@pivolio/react`](/documentation/sd-ks/react) or
[`@pivolio/next`](/documentation/sd-ks/next-js) instead — they wrap the same engine in a
provider.

#### Initialize and track

```ts
import { init, page, track } from '@pivolio/browser';

init({
  writeKey: 'wk_live_xxxxxxxxxxxx',
  apiUrl: 'https://api.pivolio.com',
});

page();
```

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

```ts
track('order_completed', {
  properties: { order_id: 'ord_123', revenue: 99.5, currency: 'USD' },
});
```

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

```ts
import { trackPurchase } from '@pivolio/browser';

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:

```ts
import { identify } from '@pivolio/browser';

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:

#### [Meta](/documentation/destinations/meta)

Conversions API

#### [Google Ads](/documentation/destinations/google-ads)

Data Manager API

#### [TikTok](/documentation/destinations/tik-tok)

Events API

#### [Reddit](/documentation/destinations/reddit)

Conversions API

## What to read next

* [Events](/documentation/core-concepts/events) — standard event names, and the taxonomy that
  decides which events earn attribution credit.
* [Configuration](/documentation/sd-ks/configuration) — every SDK option, including consent,
  batching and SPA page views.
* [First-party domains](/documentation/guides/first-party-domains) — serve the collector from
  your own subdomain to beat ad-blockers and Safari ITP.

> **Note**
>
> Events are tracked and reported immediately, but **delivery to ad platforms
> requires an active plan or trial**. If the Live Debugger shows events arriving
> while destinations stay quiet, check **Billing** first.