Skip to main content

Banner events

The banner emits browser events on the document, plus the avacy_consent event on the window. Your site code listens to them with addEventListener.

v2 banner

The v2 banner does not emit the avacy:* events and uses other ones. It also emits avacy_consent, with differences in the vendors. See JavaScript events (v2). If you don't know which banner your site uses, read Which banner your site is using.

Prerequisites​

Before you start, check that:

  • the banner is installed on the page. See HTML snippet;
  • the script with the listeners is on the page before the banner, or you use the check from step 2.

Where to listen for events​

The banner emits every avacy:* event on the document, without bubbles. Listen with document.addEventListener. A listener on window or on a page element does not receive the events.

Which event to use​

MomentEvent
When the page loadsavacy:ready
After the visitor's choiceavacy:consent-saved

After avacy:ready, getConsent() returns the saved consent. In the avacy:consent-saved listener it is already updated.

The events​

The event data is in event.detail.

EventWhen it firesdetail
avacy:readyThe banner has finished starting up and has mounted the interface.null
avacy:consent-loadedThe banner has read the saved consent, at every startup. It also fires without a saved consent, with { valid: false }.{ valid, type?, timestamp?, gcm? }
avacy:consent-savedThe visitor has made a choice.{ type, timestamp, gcm }
avacy:consent-updatedA field of the saved consent has changed without a new choice.{ fields, ... }
avacy:consent-changedThe consent has changed in any way. It fires after the specific event.{ cause?, valid, type?, timestamp?, gcm?, fields? }
avacy:banner-shownThe first-layer banner appears.{ layer: 'first' }
avacy:banner-hiddenThe first-layer banner disappears.{ reason: 'consent' }, { reason: 'destroy' } or { reason: 'dismissed' }
avacy:cpc-openedThe preferences panel opens.null
avacy:cpc-closedThe preferences panel closes.null
avacy:language-changedThe banner language changes.{ lang, prev }

What the fields contain​

The meaning of the detail fields:

  • type is 'AcceptAll', 'RejectAll' or 'Personalized'. A personalised choice equal to "accept all" or "reject all" arrives with the matching type;
  • timestamp is the time of the choice, in milliseconds since 1970;
  • gcm contains the seven Google Consent Mode permissions (ad_storage, ad_user_data, ad_personalization, analytics_storage, functionality_storage, personalization_storage, security_storage), each 'granted' or 'denied'. The field is missing if the banner does not have Google Consent Mode on;
  • valid: false means missing or expired consent, not rejected. See Reading the consent;
  • cause of avacy:consent-changed is 'decision' (visitor's choice), 'load' (read at startup) or 'record-update' (field updated);
  • reason of avacy:banner-hidden is 'consent' when the visitor has chosen and 'destroy' when the banner is reloaded. It is 'dismissed' when a rejection or a close fails because of a technical error, for example because the IAB vendor list does not download: the banner closes until the tab is closed and does not save any consent. Don't treat it as a visitor's choice.

The event data has type, time and Google permissions, without the per-vendor or per-purpose choices. For those, call window.Avacy.getConsent() in the listener.

The banner also sends avacy_consent, with the per-purpose and per-vendor choices in the detail. It emits it on the window, not on the document, and it has no avacy: prefix. Listen to it with window.addEventListener. The event exists on every web space and the dashboard turns it on by itself, through the consent-event add-on.

detail.triggerWhen it fires
page_loadThe banner has read a saved consent, at startup.
consent_updateThe visitor has made a choice, a rejection included.

Without a saved consent the event does not fire until the visitor chooses.

window.addEventListener('avacy_consent', function (event) {
console.log(event.detail.trigger, event.detail.optin, event.detail.customVendorsWithConsent);
});

The main detail fields:

  • optin is false after a full rejection, true in the other cases. Full rejections are Reject all, the X, Continue without accepting and preferences saved with everything off;
  • purposes, legitimateInterests and specialFeatures list the IAB ids with consent or with legitimate interest;
  • iabVendorsWithConsent lists the IAB vendors with vendor consent, as { id, name }. The name is missing until the preferences panel has been opened;
  • customVendorsWithConsent lists the custom vendors, as { id, name }. A vendor is included with consent to the vendor and to all the purposes it declares. A vendor with no declared purposes is included with vendor consent alone;
  • gcm is an array of the granted Consent Mode types, for example ['ad_storage']. It is not the object from avacy:consent-saved.

The banner downloads the custom vendors file, to read the declared purposes, when at least one custom vendor has consent. If the file does not arrive within 3 seconds, no custom vendor is included in customVendorsWithConsent, and the event fires anyway with the rest of the fields.

The guide Preemptive blocking with Google Tag Manager (in Italian) explains how to fire a Google Tag Manager tag per vendor with this event.

The order of events​

When a page without consent loads, the events arrive in this order:

  1. avacy:consent-loaded with { valid: false };
  2. avacy:consent-changed with cause: 'load';
  3. avacy:banner-shown;
  4. avacy:ready.

With a consent already saved, avacy:banner-shown does not fire.

After a choice, avacy:consent-saved, avacy:consent-changed with cause: 'decision' and avacy:banner-hidden with reason: 'consent' arrive.

Steps​

  1. Put the script with the listeners on the page, before the banner. The example logs every event to the console.

    <script>
    [
    'ready', 'consent-loaded', 'consent-saved', 'consent-updated', 'consent-changed',
    'banner-shown', 'banner-hidden', 'cpc-opened', 'cpc-closed', 'language-changed'
    ].forEach(function (name) {
    document.addEventListener('avacy:' + name, function (event) {
    console.log('avacy:' + name, event.detail);
    });
    });
    </script>
  2. If the script is after the banner, check the state first. The startup events (avacy:ready and avacy:consent-loaded) fire only once, and a listener registered later misses them.

    function onReady(callback) {
    var consent = window.Avacy && window.Avacy.getConsent();
    if (consent && consent.ready) {
    callback();
    } else {
    document.addEventListener('avacy:ready', callback, { once: true });
    }
    }

    onReady(function () {
    console.log('banner ready', window.Avacy.getConsent());
    });
  3. React to the visitor's choice.

    document.addEventListener('avacy:consent-saved', function (event) {
    console.log('choice:', event.detail.type);
    console.log('details:', window.Avacy.getConsent().choices);
    });

A complete example is in Running a script only with consent.

Check​

  1. Open the page with the script from step 1 and the console open, without a saved consent.
  2. Reload. The console shows avacy:consent-loaded, avacy:consent-changed, avacy:banner-shown and avacy:ready, in this order.
  3. Make a choice in the banner. The console shows avacy:consent-saved, avacy:consent-changed and avacy:banner-hidden.

Common problems​

The most frequent problems:

  • The listener on window or on an element does not fire: the avacy:* events start from the document and don't bubble up. Use document.addEventListener. The exception is avacy_consent, which is on the window;
  • The avacy_consent listener does not fire on the first visit: without a saved consent the event fires after the visitor's first choice;
  • The avacy:ready listener does not fire: you registered it after the event. Use the check from step 2;
  • event.detail.gcm is undefined: the banner does not have Google Consent Mode on. undefined does not mean "everything denied";
  • avacy:banner-hidden arrives without a visitor's choice: the banner has been reloaded (reason: 'destroy');
  • The listener fires twice for every choice: avacy:consent-saved and avacy:consent-changed fire together. Listen to only one of the two. With consent archiving on, avacy:consent-changed also fires twice, the second time with cause: 'record-update'. To react only to the visitor's choices, use avacy:consent-saved.

Last updated: 30/10/2026.