# Consent management

URL: https://pieowl.com/docs/consent-management





Some places require explicit consent before you track events or record sessions. Pieowl supports both:

* **Hold all tracking:** initialize with `disabled: true` and nothing is sent until you call `ready()`.
* **Hold only session replay:** keep **Record only after visitors agree** on, and call `allowReplay()` when the visitor accepts. Analytics keeps running.

Not sure which you need? See [Do you need a cookie banner?](/docs/consent-and-cookie-banners).

How it works [#how-it-works]

When `disabled: true` is set, all calls to `track`, `identify`, `screenView`, and session replay chunks are held in an in-memory queue instead of being sent to the API. Once the user consents, call `ready()` and the entire queue is flushed immediately.

```ts
const pieowl = new Pieowl({
  clientId: 'YOUR_CLIENT_ID',
  disabled: true, // nothing sent until ready() is called
});

// Later, when the user accepts your consent banner:
pieowl.ready();
```

If the user declines, don't call `ready()`. The queue is thrown away when the page unloads.

With the script tag, use the [`init` form](/docs/sdks/script#options-in-code), add `disabled: true` to the `init` options, and call `window.pieowl('ready')` when the user accepts.

Session replay only after consent [#session-replay-only-after-consent]

Session replay needs your visitors' consent. In **Settings → Site → What Pieowl counts**, keep **Record only after visitors agree** on when you turn replay on. It's on by default. Pieowl then doesn't start the recorder until your site calls `allowReplay()`. Page views and events are still counted.

```ts
// Script tag: when the visitor accepts in your consent banner
window.pieowl('allowReplay');

// npm package
pieowl.allowReplay();
```

If the visitor declines, don't call it. Nothing is recorded.

Pieowl stores nothing in the browser, so it doesn't remember the choice. Your consent tool does. Call `allowReplay()` on every page where the visitor has agreed, for example right after the script loads when your consent tool says yes.

With session replay and `disabled` [#with-session-replay-and-disabled]

You can use both. With `disabled: true`, replay chunks are queued like events and sent when you call `ready()`. With **Record only after visitors agree** on, the recorder also waits for `allowReplay()`. If one banner covers both, call both when the visitor accepts:

```ts
const pieowl = new Pieowl({
  clientId: 'YOUR_CLIENT_ID',
  disabled: true,
});

// User accepts consent:
pieowl.ready();
pieowl.allowReplay();
```

<Callout type="info">
  If you turn **Record only after visitors agree** off, the recorder starts as soon as the page loads and only `ready()` holds the data back. Keep the setting on so nothing is recorded before the visitor agrees.
</Callout>

Waiting for a user profile [#waiting-for-a-user-profile]

If you want to hold events until you know who the user is, rather than waiting for consent, use `waitForProfile`. Events are queued until `identify()` is called with a `profileId`.

<Callout>
  `waitForProfile` is deprecated. It still works, but for new code we recommend `disabled: true` and calling `ready()` yourself.
</Callout>

```ts
const pieowl = new Pieowl({
  clientId: 'YOUR_CLIENT_ID',
  waitForProfile: true,
});

// Events queue here...
pieowl.track('page_view');

// Queue is flushed once a profileId is set:
pieowl.identify({ profileId: 'user_123' });
```

If the user never authenticates, the queue is never flushed automatically — no events will be sent. To handle anonymous users or guest flows, call `ready()` explicitly when you know the user won't identify:

```ts
// User skipped login — flush queued events without a profileId
pieowl.ready();
```

`ready()` always releases the queue regardless of whether `waitForProfile` or `disabled` is set.

Related [#related]

* [Do you need a cookie banner?](/docs/consent-and-cookie-banners) — what Pieowl stores and when you need consent
* [Consent management guide](/guides/consent-management) — full walkthrough with a cookie banner example
* [Session replay](/docs/session-replay) — privacy controls for replay recordings
* [Identify users](/docs/get-started/identify-users) — link events to a user profile