JavaScript Events & Consent Callbacks

Last updated Aug 16, 2026

Some tools need more than script blocking - they have their own consent APIs that expect a JavaScript call when the visitor accepts or withdraws a cookie category. The Meta Pixel's fbq('consent', 'grant') is the classic example; live chat widgets and personalisation tools work the same way. The Kukie banner script gives you two mechanisms for this: a consent event you can listen to, and consent-gated script blocks that only run for consented visitors.

Whenever consent state is applied, the banner script dispatches a cc:consent-updated event on document. It fires when the visitor makes a choice (accept all, reject all, or saving custom preferences), when implied consent is recorded, and on every later page view when a returning visitor's stored consent is restored.

document.addEventListener('cc:consent-updated', function (event) {
    if (event.detail.categories.indexOf('marketing') !== -1) {
        // Marketing accepted
    } else {
        // Marketing not accepted (or withdrawn)
    }
});

The event.detail object contains:

categories - array of the accepted category slugs (e.g. ['necessary', 'marketing']).
services - array of accepted service slugs, when the site uses per-service consent; otherwise undefined.
action - what triggered the event: accept_all, reject_all, custom, update, implied, opt_out, or restore (stored consent replayed on a later page view).
consent_id - the consent receipt ID, stable across restores of the same consent.
region - the region detected for this visit.

Register your listener before the banner script runs (a plain inline <script> in your page's <head> is fine) so you never miss the restore event, which can fire as soon as the banner script boots.

Note: the category slug must match your site's category configuration. The examples on this page use the default marketing slug - check yours under Cookies & Scripts > Categories & Cookies.

Consent-gated script blocks

A script tag with type="text/plain" and a data-cc-category attribute is inert until the visitor has consented to that category. Kukie activates it at the moment consent is given and on every later page view while the consent remains valid:

<script type="text/plain" data-cc-category="marketing">
    // Runs only when the marketing category is consented
</script>

This also covers consent models where consent exists without an explicit choice: on opt-out and notice-only sites the default grant activates matching blocks on every page view, even before the visitor has interacted with the banner.

The same pattern works for iframes - set data-cc-src instead of src and the embed only loads after consent:

<iframe data-cc-src="https://example.com/embed" data-cc-category="marketing"></iframe>

Complete example: Meta Pixel manual consent

Meta's manual consent flow loads the Pixel immediately but revokes tracking until you call fbq('consent', 'grant'). Combine both mechanisms - the gated block covers returning visitors on every page view, and the listener reacts the moment a choice is made or changed:

<!-- Your Meta Pixel base code, with consent revoked by default -->
<script>
    // ... fbq base snippet ...
    fbq('consent', 'revoke');
    fbq('init', 'YOUR_PIXEL_ID');
</script>

<!-- Grant on every page view where marketing is already consented -->
<script type="text/plain" data-cc-category="marketing">
    fbq('consent', 'grant');
</script>

<!-- React the moment the visitor makes or changes a choice -->
<script>
    document.addEventListener('cc:consent-updated', function (event) {
        if (event.detail.categories.indexOf('marketing') !== -1) {
            fbq('consent', 'grant');
        } else {
            fbq('consent', 'revoke');
        }
    });
</script>

Calls made before the Pixel finishes loading are queued by the fbq stub, so the order in which these snippets execute does not matter.

Using auto-block? When Auto-block Scripts is enabled, Kukie detects the Meta Pixel loader as a marketing tracker and holds it until the visitor consents to marketing. The Pixel then never runs before consent, so the revoke call is effectively redundant - but the snippets above remain correct and are the right pattern for handling later consent withdrawal.

Two more events go in the opposite direction - your page dispatches them and the banner reacts:

// Open the consent preferences dialogue (e.g. from a footer link)
document.dispatchEvent(new CustomEvent('cc:open-preferences'));

// Grant a single category programmatically - this records a real
// consent, exactly as if the visitor had accepted it in the banner
document.dispatchEvent(new CustomEvent('cc:accept-category', {
    detail: { category: 'marketing' }
}));

Only dispatch cc:accept-category in response to a clear visitor action (for example a button that says what will be accepted) - it saves and logs consent like any banner choice.

Tip: if you just need a script to load after consent and it has no consent API of its own, you do not need any custom code - add it to the Script Centre and Kukie handles the loading logic for you.

Debug Mode

Was this helpful?

JavaScript Events & Consent Callbacks