Cookie Consent Levels

Cookie Consent Levels let you tie what the Pendo Web SDK does on a page to the consent a visitor gave in your cookie banner or consent management platform (CMP). Instead of turning the SDK fully on or off, you tell it which consent tiers the visitor agreed to, and it collects only the data those tiers allow.

How it works

Consent tiers are configured for your subscription in Pendo. Each tier has an id (for example strictlyNecessary or functional) and settings for what data can be collected. That configuration is delivered with the Web SDK, so your application only needs to pass tier ids.

Data	What a tier controls
Visitor identity	Whether the visitor can be identified and tracked. Without it, the visitor is treated as do-not-track and their session is cleared.
Analytics events	Whether analytics are collected at all, and which event types are allowed: page loads, clicks, focus, form submits, field changes, track events, identify, metadata, object metadata, and agent prompts, responses, and reactions. Analytics events also require visitor identity.
Guide analytics	Whether guide activity events (guide seen, advanced, dismissed, snoozed, poll responses, etc.) are collected.
Text collection	Whether element text is collected: none, whitelist (allowlisted text only), or all.
UTM parameters	Whether UTM parameters are stored and attached to events.
Guides	Whether guides are displayed.
Session replay	Whether sessions can be recorded. Replay also requires visitor identity.

Combining tiers

A visitor can consent to more than one tier. All data collection starts denied, and each tier the visitor consented to can only turn things on, so the result is the most permissive combination of those tiers. For example, if one tier allows whitelist text collection and another allows all, text collection is all. A tier the visitor did not consent to has no effect.

When no consent is applied

• If you never pass consent tiers, the SDK runs without consent restrictions.
• If your subscription has no consent tiers configured, consent tiers are ignored and the SDK runs without restrictions.
• If you pass a tier id that isn't configured for your subscription, the SDK logs a warning and ignores that tier.
• If you pass an empty list ([]) and tiers are configured, no data is collected.

Setting consent on initialize

When the visitor's consent is already known at page load, pass it to pendo.initialize with the cookieConsentTiers option. It accepts a single tier id or an array of tier ids, and is applied before the SDK starts tracking.

pendo.initialize({
    visitor: { id: 'put_visitor_id_here' },
    account: { id: 'put_account_id_here' },
    cookieConsentTiers: ['strictlyNecessary', 'functional']
});

Starting with no consent

If the visitor hasn't made a choice yet, initialize with an empty list. No data is collected and the visitor is treated as do-not-track until you call pendo.updateCookieConsent. Because the visitor isn't identified while consent is denied, pass their identity when you update consent:

pendo.initialize({
    visitor: { id: 'put_visitor_id_here' },
    account: { id: 'put_account_id_here' },
    cookieConsentTiers: []
});

// Later, once the visitor accepts in your cookie banner
pendo.updateCookieConsent(['strictlyNecessary', 'functional'], {
    visitor: { id: 'put_visitor_id_here' },
    account: { id: 'put_account_id_here' }
});

Updating consent

When the visitor changes their consent after the SDK has initialized, call pendo.updateCookieConsent with the full set of tiers they now consent to. The new tiers replace the previous ones and take effect immediately: guides are shown or hidden, session replay starts or stops, and event collection is adjusted.

pendo.updateCookieConsent(['strictlyNecessary', 'functional']);

updateCookieConsent returns what data is now collected, which is useful for debugging:

{
    identity: true,
    guides: true,
    replay: false,
    utm: false,
    analytics: ['load', 'click'],
    guideAnalytics: ['guideSeen', 'guideAdvanced' /* ... */],
    textCollection: 'whitelist'
}

Resuming visitor identity

If a visitor starts on a tier that does not allow identity, the SDK treats them as do-not-track and has no identity to resume. When they later consent to a tier that allows identity, pass their visitor and account as the second argument, in the same shape as pendo.updateOptions:

pendo.updateCookieConsent(['strictlyNecessary', 'functional'], {
    visitor: { id: 'put_visitor_id_here' },
    account: { id: 'put_account_id_here' }
});

The identity is only applied when consent moves a do-not-track visitor to a tier that allows identity, and is ignored otherwise.

Frames

When the SDK runs in multiple frames of the same application, a consent change made with updateCookieConsent in one frame is applied in the others, and child frames that load later receive the current consent. See frame support for installing the SDK in frames.

Example: connecting a consent management platform

Most CMPs expose the visitor's consented categories and an event that fires when they change. Map those categories to your Pendo tier ids, pass them on initialize, and call updateCookieConsent on change:

function getPendoTiers() {
    // Replace with your CMP's API and your subscription's tier ids
    var tiers = ['strictlyNecessary'];
    if (myCmp.hasConsent('functional')) tiers.push('functional');
    if (myCmp.hasConsent('analytics')) tiers.push('analytics');
    return tiers;
}

pendo.initialize({
    visitor: { id: 'put_visitor_id_here' },
    account: { id: 'put_account_id_here' },
    cookieConsentTiers: getPendoTiers()
});

myCmp.onConsentChanged(function() {
    pendo.updateCookieConsent(getPendoTiers(), {
        visitor: { id: 'put_visitor_id_here' },
        account: { id: 'put_account_id_here' }
    });
});