JavaScript events and consent callbacks

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.

The cc:consent-updated event

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 consent is implied without a choice, and on every later page view when a returning visitor's stored consent is restored.

In a region set to Hidden, where no banner shows, the event fires on every page view with the action implied and every category. If the visitor made a choice earlier, for example through your "Do Not Sell or Share" link, that choice is restored instead and the event carries the action restore.

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, accept_category (a single category accepted outside the banner - a blocked embed's Accept button, or one of the hooks described under "Trigger banner actions from your own code"), or restore (stored consent replayed on a later page view).
• consent_id - the consent receipt ID, stable across restores of the same consent. It is null for the implied grant in a Hidden region, because nothing is saved or logged there.
• 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.

The cc:banner-state event

Once on every page view, the banner script dispatches a cc:banner-state event on document. It says what the banner did on that page: it appeared, it applied a choice the visitor made earlier, or it stayed out of sight. Use it to count how often your banner appears, or to wait until the banner has decided before you show something of your own.

document.addEventListener('cc:banner-state', function (event) {
    if (event.detail.state === 'shown') {
        // The banner or the cookie wall is on screen
    }
});

The event.detail object contains:

• state - shown (the banner or the cookie wall appeared), restored (the visitor's stored choice was applied, so no banner appeared), hidden (the visitor's region is set to Hidden) or suppressed (the page matches your Disabled Pages list).
• surface - only with shown: banner, or wall for the cookie wall.
• grant - only with restored: all when the stored choice accepts every optional category, none when it accepts none of them, and partial otherwise.
• signal - gpc or dnt when the visitor's Global Privacy Control or Do Not Track signal rejected optional cookies on this page view, otherwise null. It needs Respect Global Privacy Control or Respect Do Not Track turned on in Banner Editor > Behaviour. A stored choice takes priority over the signal, so with restored it is always null.
• model - the consent model applied on this page view: opt_in, opt_out, notice_only or hidden.
• lang - the language the banner uses on this page, for example en or pt-br.

The event fires after the banner has looked up the visitor's region, and only once per page view: reopening the banner, a choice and cc:open-preferences do not fire it again. It does not fire when Banner display status is off in Site Settings, on a domain other than your site's, or while the Kukie.io cookie scanner checks your pages. Register your listener before the banner script runs, as for cc:consent-updated.

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. The address must be an http:// or https:// URL (or a relative one); anything else is never loaded:

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

Trigger banner actions from your own code

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

// Open the cookie preferences panel with the per-category toggles
// (e.g. from a "Cookie Settings" link in your footer). Works even
// when the banner's own Customise button is hidden.
document.dispatchEvent(new CustomEvent('cc:open-preferences'));

// Re-open the first banner layer instead of the panel
document.dispatchEvent(new CustomEvent('cc:open-banner'));

// 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 consent like any banner choice and is logged in your Consent Log as "Accept Category". The category must be one your site has configured as optional; a required category, or a slug your site does not have, is ignored.

The same actions without JavaScript

An element carrying one of these attributes does the same thing when clicked. The banner script listens for the click on the whole page, so links rendered later - a footer from your theme, a single-page app view - work too, and the click's default action is cancelled so an href="#" never scrolls the page:

<a href="#" data-cc-open-preferences>Cookie Settings</a>

<button type="button" data-cc-accept-category="marketing">Allow marketing cookies</button>

Put data-cc-accept-category on the button or link itself - a <button>, an <a> or an element with role="button". On a wrapper around other content it does nothing: a click on a link or on text inside a <div data-cc-accept-category> is never treated as consent, so a visitor cannot accept cookies by accident. The same category rule as for the event applies.

The placeholders shown for blocked iFrames use exactly these attributes for their own two buttons.

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.