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.
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
| Moment | Event |
|---|---|
| When the page loads | avacy:ready |
| After the visitor's choice | avacy: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.
| Event | When it fires | detail |
|---|---|---|
avacy:ready | The banner has finished starting up and has mounted the interface. | null |
avacy:consent-loaded | The 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-saved | The visitor has made a choice. | { type, timestamp, gcm } |
avacy:consent-updated | A field of the saved consent has changed without a new choice. | { fields, ... } |
avacy:consent-changed | The consent has changed in any way. It fires after the specific event. | { cause?, valid, type?, timestamp?, gcm?, fields? } |
avacy:banner-shown | The first-layer banner appears. | { layer: 'first' } |
avacy:banner-hidden | The first-layer banner disappears. | { reason: 'consent' }, { reason: 'destroy' } or { reason: 'dismissed' } |
avacy:cpc-opened | The preferences panel opens. | null |
avacy:cpc-closed | The preferences panel closes. | null |
avacy:language-changed | The banner language changes. | { lang, prev } |
What the fields contain
The meaning of the detail fields:
typeis'AcceptAll','RejectAll'or'Personalized'. A personalised choice equal to "accept all" or "reject all" arrives with the matching type;timestampis the time of the choice, in milliseconds since 1970;gcmcontains 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: falsemeans missing or expired consent, not rejected. See Reading the consent;causeofavacy:consent-changedis'decision'(visitor's choice),'load'(read at startup) or'record-update'(field updated);reasonofavacy:banner-hiddenis'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 avacy_consent event
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.trigger | When it fires |
|---|---|
page_load | The banner has read a saved consent, at startup. |
consent_update | The 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:
optinisfalseafter a full rejection,truein the other cases. Full rejections are Reject all, the X, Continue without accepting and preferences saved with everything off;purposes,legitimateInterestsandspecialFeatureslist the IAB ids with consent or with legitimate interest;iabVendorsWithConsentlists the IAB vendors with vendor consent, as{ id, name }. The name is missing until the preferences panel has been opened;customVendorsWithConsentlists 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;gcmis an array of the granted Consent Mode types, for example['ad_storage']. It is not the object fromavacy: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:
avacy:consent-loadedwith{ valid: false };avacy:consent-changedwithcause: 'load';avacy:banner-shown;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
-
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> -
If the script is after the banner, check the state first. The startup events (
avacy:readyandavacy: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());}); -
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
- Open the page with the script from step 1 and the console open, without a saved consent.
- Reload. The console shows
avacy:consent-loaded,avacy:consent-changed,avacy:banner-shownandavacy:ready, in this order. - Make a choice in the banner. The console shows
avacy:consent-saved,avacy:consent-changedandavacy:banner-hidden.
Common problems
The most frequent problems:
- The listener on
windowor on an element does not fire: theavacy:*events start from thedocumentand don't bubble up. Usedocument.addEventListener. The exception isavacy_consent, which is on thewindow; - The
avacy_consentlistener does not fire on the first visit: without a saved consent the event fires after the visitor's first choice; - The
avacy:readylistener does not fire: you registered it after the event. Use the check from step 2; event.detail.gcmisundefined: the banner does not have Google Consent Mode on.undefineddoes not mean "everything denied";avacy:banner-hiddenarrives without a visitor's choice: the banner has been reloaded (reason: 'destroy');- The listener fires twice for every choice:
avacy:consent-savedandavacy:consent-changedfire together. Listen to only one of the two. With consent archiving on,avacy:consent-changedalso fires twice, the second time withcause: 'record-update'. To react only to the visitor's choices, useavacy:consent-saved.
Last updated: 30/10/2026.