Passa al contenuto principale

Consent Actions

Metodi per scrivere il consenso (programmaticamente, oppure come reazione a UI custom esterne al banner).

MethodTierSince
acceptAll(options?)13.0
rejectAll(options?)13.0
updateConsent(patches)13.0
triggerConsent(payload)13.0

Per leggere il consenso vedi Consent query. Per cambiare lingua durante una sessione vedi changeLanguage.

Tutte le chiamate via window.Avacy.* stampano screen: 'api' nel payload audit del core (vedi ConsentScreen sotto). Il banner UI e il CPC restano 'first' / 'second'.

Il type salvato può non essere quello chiesto. Dopo ogni scrittura Personalized il core confronta le scelte risultanti con quelle che darebbero AcceptAll e RejectAll sugli stessi framework: se coincidono, il consenso viene salvato (ed emesso in avacy:consent-saved) come AcceptAll o RejectAll.

acceptAll​

Zucchero per accettare tutti i purposes e vendors di tutti i framework configurati. Equivalente a triggerConsent({ type: 'AcceptAll', screen: 'api' }).

Accetta opzionalmente except per escludere selettivamente alcuni elementi (utile per casi tipo "accetta tutto tranne questo vendor", senza dover costruire un Personalized da zero).

window.Avacy.acceptAll(options?: { except?: PrivacySelector[] }): Promise<void>

type PrivacySelector =
  | `${'tcf' | 'gcm' | 'acm'}:${'purpose' | 'vendor' | 'specialFeature' | 'customPurpose'}:${number}`
  | `custom:${'purpose' | 'vendor' | 'specialFeature' | 'customPurpose'}:${string}`;

Parameters​

NameTypeDescription
options.exceptPrivacySelector[] (opzionale)Lista di selettori framework:type:id da escludere dall'accept. Se omesso o vuoto, equivalente a chiamata senza argomenti. L'id è numerico per tcf, gcm e acm, testuale per custom, dove porta il prefisso dell'origine (es. custom:vendor:d116). Selettori malformati vengono ignorati.

Returns​

Promise<void> — risolta quando il consenso è scritto nello store e i framework hanno propagato (TCString aggiornato, __tcfapi ping consentente, Google CMode default→update, etc.).

Examples​

<button onclick="window.Avacy.acceptAll()">Accetta tutto</button>
// Accetta tutto tranne TCF vendor 79, GCM purpose 4 (analytics_storage) e il fornitore custom d116:
await window.Avacy.acceptAll({
  except: ['tcf:vendor:79', 'gcm:purpose:4', 'custom:vendor:d116'],
});

// Identità: except vuoto = nessuna eccezione
await window.Avacy.acceptAll({ except: [] });
await window.Avacy.acceptAll();

Side effects​

  • Senza except (o con except: []): emette avacy:consent-saved { type: 'AcceptAll', timestamp, gcm }.
  • Con except non vuoto: la scrittura parte come Personalized, e di norma esce avacy:consent-saved { type: 'Personalized', … }. Se però le scelte risultanti coincidono con quelle di un AcceptAll (consenso e legittimo interesse, scelta per scelta), il core salva AcceptAll (vedi la nota in cima).

rejectAll​

Speculare a acceptAll. Rifiuta tutti i purposes e vendors di tutti i framework configurati, con opzionale except per consentire selettivamente.

window.Avacy.rejectAll(options?: { except?: PrivacySelector[] }): Promise<void>

Examples​

<button onclick="window.Avacy.rejectAll()">Rifiuta tutto</button>
// Rifiuta tutto tranne TCF purpose 1 (cookie tecnici):
await window.Avacy.rejectAll({
  except: ['tcf:purpose:1'],
});

Side effects​

  • Senza except: emette avacy:consent-saved { type: 'RejectAll', timestamp, gcm }.
  • Con except non vuoto: come per acceptAll, di norma type: 'Personalized', ma RejectAll se le scelte risultanti coincidono con quelle di un rifiuto totale.

Comportamento legitimate interest: il default (objectLegIntOnReject: true) cancella i LI su purposes/vendors quando si rifiuta. Per preservarli vedi config TCF/Custom framework objectLegIntOnReject: false. Lo stesso comportamento si applica agli elementi non in except quando si usa rejectAll({ except }).

updateConsent​

Patch puntuale del consenso corrente: flippa solo i selettori elencati, gli altri restano allo stato corrente. La scrittura parte come Personalized; se il risultato coincide con un accetta/rifiuta tutto, il core la salva come AcceptAll/RejectAll (vedi la nota in cima).

window.Avacy.updateConsent(patches: ConsentPatches): Promise<void>

type ConsentPatches = Partial<Record<PrivacySelector, boolean>>;

Parameters​

NameTypeDescription
patchesRecord<PrivacySelector, boolean>Mappa framework:type:id → next hasConsent. Stessa sintassi del campo except di acceptAll / rejectAll. Selettori malformati vengono droppati silenziosamente. Patch vuota è un no-op (nessun consent write dispatcato).

Examples​

// Toggle puntuale di 1-2 selettori senza modificare il resto del consenso corrente.
await window.Avacy.updateConsent({
  'tcf:vendor:32': true,
  'tcf:purpose:1': false,
});
// Caso d'uso: UI custom con switch per singolo vendor.
toggleEl.addEventListener('change', (e) => {
  window.Avacy.updateConsent({
    [`tcf:vendor:${vendorId}`]: e.target.checked,
  });
});
// Patch vuota = no-op (nessun consent write, nessun avacy:consent-saved).
await window.Avacy.updateConsent({});

Side effects​

Emette avacy:consent-saved { type, timestamp, gcm } quando almeno un selettore sintatticamente valido è presente nei patches. type è 'Personalized', oppure 'AcceptAll'/'RejectAll' se dopo la patch le scelte coincidono con quelle di un accetta/rifiuta tutto.

Garanzia di preservazione: il payload viene costruito a partire da consent.choices corrente. Per i framework che ricostruiscono le choices a partire dal template customization.privacySettings (es. TCF), i selettori che non sono nel template potrebbero non essere preservati a runtime — è un comportamento del core TCF adapter, tracciato fuori da questa preview. Per i casi di test l'asserzione minimale è "il selettore patchato è applicato + consent.type passa a Personalized".

See also​

triggerConsent​

API raw per scrivere un payload di consenso arbitrario (AcceptAll, RejectAll, Personalized). Il tipo CloseBanner esiste nel payload ma non scrive nessun consenso: vedi sotto.

window.Avacy.triggerConsent(payload: OnConsentPayload): Promise<void>

Parameters​

NameTypeDescription
payloadOnConsentPayloadPayload tipizzato. Forma dipende dal type (AcceptAll, RejectAll, Personalized, CloseBanner). screen può mancare: se è assente o non è 'first'/'second'/'api', viene registrato 'api'.

Payload variants​

Il type agisce da discriminator. Le shape:

type ConsentScreen = 'first' | 'second' | 'api';

type OnConsentPayload =
  | { type: 'AcceptAll'; screen?: ConsentScreen }
  | { type: 'RejectAll'; screen?: ConsentScreen }
  | { type: 'CloseBanner'; screen?: ConsentScreen }
  | { type: 'Personalized'; screen?: ConsentScreen; privacyChoices: PrivacyChoice[] };

Nel tipo TypeScript screen è obbligatorio; a runtime window.Avacy.triggerConsent lo completa con 'api' quando manca o non è valido.

PrivacyChoice — vedi Tier 2. L'id è un numero per tcf, gcm e acm e una stringa per i fornitori custom (es. 'd116').

Example: AcceptAll​

await window.Avacy.triggerConsent({ type: 'AcceptAll', screen: 'api' });

Example: Personalized​

await window.Avacy.triggerConsent({
  type: 'Personalized',
  screen: 'api',
  privacyChoices: [
    { framework: 'tcf', type: 'purpose', id: 1, hasConsent: true, hasLegitimateInterest: false },
    { framework: 'tcf', type: 'purpose', id: 2, hasConsent: false, hasLegitimateInterest: true },
    { framework: 'tcf', type: 'vendor',  id: 755, hasConsent: true, hasLegitimateInterest: false },
  ],
});

CloseBanner: nessun consenso scritto​

await window.Avacy.triggerConsent({ type: 'CloseBanner', screen: 'api' });
// → nessuna scrittura nello store, nessun avacy:consent-saved, il banner resta

Il listener del consenso del core esce subito su CloseBanner, senza salvare niente: non equivale a RejectAll. Il payload arriva solo agli add-on. Il bottone "Continua senza accettare" del banner non usa CloseBanner: salva un RejectAll.

Side effects​

Per AcceptAll, RejectAll e Personalized emette avacy:consent-saved { type, timestamp, gcm }. type è quello salvato, che per un Personalized può diventare AcceptAll o RejectAll (vedi la nota in cima). CloseBanner non emette nulla.

ConsentScreen​

Audit field stampato su ogni consent write, drive consentScreen nel TCString:

ValoreSignificatoTCString consentScreen
'first'Banner UI / first layer1
'second'Preference Center / second layer2
'api'Programmatic via window.Avacy.*2 (una scrittura via API è un cambio di preferenze)

Il campo ConsentScreen del TC String è un intero a 6 bit, non una stringa. Ogni consenso che il CMP scrive registra 1 o 2.

Banner e CPC components passano direttamente 'first' / 'second' al core. acceptAll, rejectAll e updateConsent stampano sempre 'api'; triggerConsent usa lo screen del payload se è uno dei tre valori, altrimenti 'api'.

See also​