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?.

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.

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, add disabled: true to the init options, and call window.pieowl('ready') when the user accepts.

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.

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

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:

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

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

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.

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:

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

• Do you need a cookie banner? — what Pieowl stores and when you need consent
• Consent management guide — full walkthrough with a cookie banner example
• Session replay — privacy controls for replay recordings
• Identify users — link events to a user profile