API Privacy & Messaging JavaScript

Introduzione

Questa API fornisce strumenti per interagire con i messaggi offerti dalla scheda Privacy e messaggi. che ti consente di:

  • elimina i messaggi per un determinato utente
  • eseguire una query sullo stato di blocco degli annunci di un utente
  • Consenti a un utente di revocare il consenso (se applicabile)

Puoi utilizzare questi strumenti anche per raccogliere il consenso degli utenti utilizzando alcuni protocolli standard di settore:

In questi casi, lo stato del consenso viene comunicato tramite queste API.

Puoi implementare questa funzionalità di messaggistica per gli utenti sul tuo sito in due modi:

  1. Nella maggior parte dei casi, non è necessario eseguire nuovamente la codifica: il tag publisher di Google o il tag AdSense esistente implementa i messaggi per gli utenti dopo che il messaggio è stato pubblicato nel prodotto pertinente.
  2. Se utilizzi il messaggio di risposta al blocco degli annunci, devi aggiungere esplicitamente il tag per il blocco degli annunci alla tua pagina. Per ulteriori informazioni, consulta le istruzioni sul tagging di Ad Manager e AdSense.

googlefc è lo spazio dei nomi globale che la funzionalità di messaggistica per gli utenti utilizza per la sua API su JavaScript Window.

Riepiloghi dei campi

Nome Tipo Definizione
googlefc.controlledMessagingFunction funzione(!Object) Una funzione che determina se procedere con i messaggi. Questa funzionalità è supportata per tutti i tipi di messaggi.
googlefc.callbackQueue !Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue Riferimento alla coda di callback per l'esecuzione asincrona delle query di messaggistica degli utenti.
googlefc.CallbackQueue !Oggetto Il tipo di oggetto coda di callback.
googlefc.AdBlockerStatusEnum !Object<stringa, numero> Un'enumerazione per rappresentare lo stato di blocco degli annunci dell'utente.
googlefc.AllowAdsStatusEnum !Object<stringa, numero> Un'enumerazione per rappresentare lo stato di autorizzazione degli annunci dell'utente.
googlefc.ccpa.InitialCcpaStatusEnum !Object<stringa, numero> Un'enum che rappresenta lo stato iniziale del CPRA dell'utente.
googlefc.ccpa.overrideDnsLink undefined|boolean Un valore booleano che può essere impostato su true per utilizzare un link personalizzato Non vendere.

Riepiloghi dei metodi

Nome Tipo restituito Definizione
googlefc.showRevocationMessage() non definito Cancella il record relativo al consenso e ricarica lo script googlefc per mostrare il messaggio per il consenso applicabile all'utente.
googlefc.getAdBlockerStatus() numero Restituisce un valore in AdBlockerStatusEnum che dipende dallo stato di blocco degli annunci dell'utente.
googlefc.getAllowAdsStatus() numero Restituisce un valore in AllowAdsStatusEnum a seconda dello stato di autorizzazione degli annunci dell'utente.
googlefc.ccpa.getInitialCcpaStatus() numero Restituisce un valore in InitialCcpaStatusEnum in base allo stato CPRA iniziale dell'utente.
googlefc.ccpa.openConfirmationDialog(function(boolean)) non definito Apre la finestra di dialogo di conferma CPRA se viene eseguito l'override del link Non vendere predefinito.

Test e debug sul tuo sito

Privacy e messaggi offre funzionalità di debug e test che ti consentono di visualizzare l'aspetto di messaggi specifici (o combinazioni di messaggi) sul tuo sito effettivo.

Prerequisiti:

  • I messaggi di cui vuoi visualizzare l'anteprima devono essere pubblicati nel sito su cui stai eseguendo il test

Puoi visualizzare un'anteprima in tempo reale sul tuo sito utilizzando i seguenti parametri URL di debug:

Parametro di debug Valori consentiti
fc alwaysshow (per attivare la modalità di debug/anteprima)
fctype ab (messaggi per il blocco degli annunci), ccpa (messaggi di disattivazione CPRA), gdpr (messaggi per il consenso GDPR), monetization (messaggi della Offerwall)

Ecco alcuni esempi di come utilizzare questa funzionalità per visualizzare l'anteprima sul tuo sito (foo.com):

  • Messaggio di test CPRA: http://foo.com/?fc=alwaysshow&fctype=ccpa
  • Messaggio GDPR di prova -- http://foo.com/?fc=alwaysshow&fctype=gdpr

Campi: spiegazioni ed esempi

googlefc.controlledMessagingFunction {function(!Object)}

Una funzione che determina se i messaggi devono essere visualizzati o meno. Può essere utilizzata per limitare il rendering dei messaggi in base a condizioni specificate dall'editore, come lo stato dell'abbonato o l'URL della pagina.

Quando definisci googlefc.controlledMessagingFunction nella finestra prima del caricamento di altri script, i messaggi non vengono visualizzati finché non chiami message.proceed(boolean). La chiamata a message.proceed(true) consente il normale svolgimento dei messaggi, mentre la chiamata a message.proceed(false) impedisce la visualizzazione di tutti i messaggi nella visualizzazione di pagina.

Esempio: supponiamo di avere questo script nella pagina che definisce una funzione asincrona determineIfUserIsSubscriber() che verifica se l'utente che ha eseguito l'accesso è un abbonato.

<head>
  <script>
    window.isSubscriber = undefined;
    function determineIfUserIsSubscriber() {
      if (isSubscriber !== undefined) {
        return isSubscriber;
      }
      return new Promise(resolve => {
        setTimeout(() => {
          // Change this to true if you want to test what subscribers would see.
          window.isSubscriber = false;
          resolve(window.isSubscriber);
        }, 1000);
      });
    }
  </script>
</head>

Questo è un esempio di come puoi utilizzare googlefc.controlledMessagingFunction per mostrare il messaggio solo ai non abbonati.

<head>
  <script>
    // Define googlefc and the controlled messaging function on the Window.
    window.googlefc = window.googlefc || {};
    googlefc.controlledMessagingFunction = async (message) => {
      // Determine if the user is a subscriber asynchronously.
      const isSubscriber = await determineIfUserIsSubscriber();

      if (isSubscriber) {
        // If the user is a subscriber, don't show any messages.
        message.proceed(false);
      } else {
        // Otherwise, show messages as usual.
        message.proceed(true);
      }
    }
  </script>
</head>

Esiste anche un'estensione di questa funzionalità che consente ai publisher che fanno parte della versione beta chiusa della Offerwall di specificare che deve essere soppressa solo la Offerwall. Gli altri tipi di messaggi non sono interessati quando questa funzionalità è attiva.

La messaggistica controllata specifica della Offerwall si ottiene passando un parametro aggiuntivo a message.proceed(), un Array di tipo googlefc.MessageTypeEnum.

Esempio: questo è un esempio di utilizzo di googlefc.controlledMessagingFunction per eliminare solo la pubblicazione della Offerwall per gli abbonati, senza eliminare altri tipi di messaggi:

<head>
  <script>
    // Define googlefc and the controlled messaging function on the Window.
    window.googlefc = window.googlefc || {};
    googlefc.controlledMessagingFunction = async (message) => {
     // Determine if the Offerwall should display or not.
     const shouldDisplayOfferwall = await determineIfUserIsSubscriber();
     const applicableMessageTypes = [];

     if (!shouldDisplayOfferwall) {
       // Do not show the Offerwall, but allow other message types to display.
       applicableMessageTypes.push(window.googlefc.MessageTypeEnum.OFFERWALL);
       message.proceed(false, applicableMessageTypes);
     } else {
       // Otherwise, show messages as usual.
       message.proceed(true);
     }
    }
  </script>
</head>

googlefc.callbackQueue {!Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue}

Riferimento alla coda di callback globale per l'esecuzione asincrona delle chiamate correlate alla messaggistica. L'unico modo supportato per richiamare una funzione è aggiungendola a callbackQueue.

Poiché diversi tipi di dati diventano disponibili in momenti diversi, è necessario aggiungere una funzione come mappa, con una delle seguenti stringhe come chiave e la funzione da eseguire come valore.

Chiavi supportate:

Nome chiave Utilizzo Latenza relativa
CONSENT_API_READY Le funzioni inviate alla coda di callback con la chiave CONSENT_API_READY vengono eseguite quando le API per i framework di consenso supportati sono definite e richiamabili. Da questo momento in poi, l'esecuzione di qualsiasi funzione con chiave CONSENT_API_READY aggiunta successivamente è sincrona. Per informazioni dettagliate, consulta le sezioni sui framework IAB. Bassa
CONSENT_DATA_READY Le funzioni inviate alla coda di callback con la chiave CONSENT_DATA_READY vengono eseguite quando è noto il consenso dell'utente raccolto nell'ambito di un framework per il consenso supportato (da un'esecuzione precedente o dopo che l'utente ha interagito con il messaggio per il consenso). Da questo momento in poi, l'esecuzione di qualsiasi funzione con chiave CONSENT_DATA_READY aggiunta successivamente è sincrona. Alta
AD_BLOCK_DATA_READY Le funzioni inviate alla coda di callback con il tasto AD_BLOCK_DATA_READY vengono eseguite quando i dati relativi al blocco degli annunci diventano disponibili nel flusso. Da questo momento in poi, l'esecuzione di tutte le funzioni con chiave AD_BLOCK_DATA_READY aggiunte successivamente è sincrona. Alta
INITIAL_CCPA_DATA_READY Le funzioni inviate alla coda di callback con INITIAL_CCPA_DATA_READY vengono eseguite quando i dati CPRA diventano disponibili nel flusso. Tieni presente che eventuali richieste successive relative ai dati CPRA devono essere ottenute chiamando direttamente l'API US Privacy (__uspapi). Media

googlefc.CallbackQueue {!Object}

Riepilogo del metodo:

Nome Tipo Parametro Tipo restituito Ruolo
push(data) numero data: una coppia chiave-valore con la chiave come uno dei tipi di disponibilità dei dati e il valore come funzione JavaScript da eseguire. Le chiavi di disponibilità dei dati accettabili sono CONSENT_API_READY, CONSENT_DATA_READY, AD_BLOCK_DATA_READY e INITIAL_CCPA_DATA_READY. Il numero di comandi aggiunti finora. Restituisce la lunghezza corrente dell'array. Esegue la funzione trasmessa, nell'ordine in cui i dati diventano disponibili e in base all'ordine in cui queste funzioni vengono aggiunte alla coda.

Esempio:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'AD_BLOCK_DATA_READY':
    () => {
      if (googlefc.getAdBlockerStatus() == googlefc.AdBlockerStatusEnum.NO_AD_BLOCKER) {
        // Handle a non-ad blocking user.
      }
    }
  });
</script>

googlefc.AdBlockerStatusEnum {!Object<string, number>}

Rappresenta i diversi stati di blocco degli annunci dell'utente. I diversi stati sono:

googlefc.AdBlockerStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  // The user was running an extension level ad blocker.
  EXTENSION_AD_BLOCKER: 1,
  // The user was running a network level ad blocker.
  NETWORK_LEVEL_AD_BLOCKER: 2,
  // The user was not blocking ads.
  NO_AD_BLOCKER: 3,
};

googlefc.AllowAdsStatusEnum {!Object<string, number>}

Rappresenta i diversi stati di autorizzazione degli annunci per il blocco degli annunci dell'utente. I diversi stati sono:

googlefc.AllowAdsStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  // User is currently using an ad blocker, was never using an ad blocker, or
  // allowed ads, but not because they saw the Privacy & messaging message.
  ADS_NOT_ALLOWED: 1,
  // User is no longer using an ad blocker after seeing the ad blocking message.
  ADS_ALLOWED: 2,
};

googlefc.ccpa.InitialCcpaStatusEnum{!Object<string, number>}

Rappresenta i diversi stati di autorizzazione degli annunci per il blocco degli annunci dell'utente. I diversi stati sono:

googlefc.ccpa.InitialCcpaStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  // CPRA does not apply to this user.
  CCPA_DOES_NOT_APPLY: 1,
  // CPPA applies to this user, and the user has not opted out yet.
  NOT_OPTED_OUT: 2,
  // CPPA applies to this user, and the user has opted out.
  OPTED_OUT: 3,
};

googlefc.ccpa.overrideDnsLink{undefined|boolean}

Imposta questo campo su true per nascondere il link predefinito Non vendere e utilizzare un link personalizzato Non vendere.

Esempio:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  // Signals that the default DNS link will be overridden.
  googlefc.ccpa.overrideDnsLink = true;
</script>

Metodi: spiegazioni ed esempi

googlefc.getConsentStatus(): {number}

googlefc.getConsentedProviderIds(): {!Array<string>}

  1. Ora, quando viene richiamato, questo restituisce sempre un elenco vuoto.

googlefc.showRevocationMessage(): {undefined}

Cancella l'attuale record relativo al consenso e mostra il messaggio per il consenso applicabile a questo utente. La chiave che deve essere specificata per questa funzione è CONSENT_DATA_READY.

Esempio:

<button type="button" onclick="googlefc.callbackQueue.push({'CONSENT_DATA_READY': () => googlefc.showRevocationMessage()});">
  Click here to revoke
</button>

googlefc.getAdBlockerStatus(): {number}

Restituisce un valore in AdBlockerStatusEnum a seconda dello stato di blocco degli annunci dell'utente. La chiave che deve essere specificata per questa funzione è AD_BLOCK_DATA_READY.

Esempio:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'AD_BLOCK_DATA_READY':
    () => {
      switch (googlefc.getAdBlockerStatus()) {
          case googlefc.AdBlockerStatusEnum.EXTENSION_LEVEL_AD_BLOCKER:
          case googlefc.AdBlockerStatusEnum.NETWORK_LEVEL_AD_BLOCKER:
            // Insert handling for cases where the user is blocking ads.
            break;
          case googlefc.AdBlockerStatusEnum.NO_AD_BLOCKER:
            // Insert handling for cases where the user is not blocking ads.
            break;
          case googlefc.AdBlockerStatusEnum.UNKNOWN:
            // Insert handling for unknown cases.
            break;
      }
    }
  });
</script>

googlefc.getAllowAdsStatus(): {number}

Restituisce un valore in AllowAdsStatusEnum a seconda dello stato di autorizzazione degli annunci dell'utente. La chiave che deve essere specificata per questa funzione è AD_BLOCK_DATA_READY.

Esempio:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'AD_BLOCK_DATA_READY':
    () => {
      switch (googlefc.getAllowAdsStatus()) {
        case googlefc.AllowAdsStatusEnum.ADS_NOT_ALLOWED:
          // Insert handling for cases where the user has not allowed ads.
          // The user may have never been an ad blocker.
          break;
        case googlefc.AllowAdsStatusEnum.ADS_ALLOWED:
          // Insert handling for cases where the user saw the ad blocking
          // message and allowed ads on the site.
          break;
        case googlefc.AllowAdsStatusEnum.UNKNOWN:
          // Insert handling for unknown cases.
          break;
      }
    }
  });
</script>

googlefc.ccpa.getInitialCcpaStatus(): {number}

Restituisce un valore in InitialCcpaStatusEnum a seconda dello stato CPRA dell'utente. La chiave che deve essere specificata per questa funzione è INITIAL_CCPA_DATA_READY. Tieni presente che eventuali richieste successive di dati CPRA devono essere ottenute chiamando direttamente l'API US Privacy (__uspapi).

Esempio:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'INITIAL_CCPA_DATA_READY':
    () => {
      switch (googlefc.ccpa.getInitialCcpaStatus()) {
        case googlefc.ccpa.InitialCcpaStatusEnum.CCPA_DOES_NOT_APPLY:
          // Insert handling for cases where the user is not CPRA eligible.
          break;
        case googlefc.ccpa.InitialCcpaStatusEnum.NOT_OPTED_OUT:
          // Insert handling for cases where the user is CPRA eligible and has
          // not opted out.
          break;
        case googlefc.ccpa.InitialCcpaStatusEnum.OPTED_OUT:
          // Insert handling for cases where the user is CPRA eligible and has
          // opted out.
          break;
      }
    }
  });
</script>

googlefc.ccpa.openConfirmationDialog(function(boolean)): {undefined}

Apre la finestra di dialogo di conferma CPRA se viene eseguito l'override del link predefinito Non vendere. Una volta che l'utente interagisce con la finestra di dialogo di conferma, la funzione di callback fornita viene richiamata con true se l'utente decide di disattivarla e con false in caso contrario.

Esempio:

<script>
// This callback will be called with the user CPRA decision.
const ccpaCompletionCallback = (userOptedOut) => {
  // Insert handling for user opt-out status here.
}
// Invoke the CPRA confirmation dialog when the user clicks the link.
document.getElementById("your-custom-ccpa-do-not-sell-link").addEventListener(
  "click", () => googlefc.ccpa.openConfirmationDialog(ccpaCompletionCallback));
</script>

Se utilizzi le soluzioni di gestione del consenso di Google per ottenere il consenso GDPR nell'ambito della versione 2 del TCF di IAB, devi utilizzare l'API della versione 2 del TCF di IAB.

Puoi utilizzare la chiave della coda di callback di CONSENT_API_READY per assicurarti che i callback corrispondenti vengano richiamati solo quando nella pagina viene definita l'API della versione 2 del TCF di IAB. Deve essere utilizzato in combinazione con il comando 'addEventListener' dell'API TCF v2 di IAB.

Esempio:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback using the CONSENT_API_READY key on the callbackQueue.
  window.googlefc.callbackQueue.push({
    'CONSENT_API_READY':
    () => __tcfapi('addEventListener', 2.2, (data, success) => {
      // Do something with consent data value; this callback may be invoked
      // multiple times as user completes consent flow.
    })
  });
</script>

Puoi utilizzare la chiave della coda di callback CONSENT_DATA_READY per assicurarti che i callback corrispondenti vengano richiamati solo quando il consenso dell'utente viene raccolto e accessibile utilizzando l'API TCF v2 di IAB. Questa opzione può essere utilizzata in combinazione con il comando 'addEventListener': i dati forniti nella prima chiamata del callback fornito conterranno le selezioni dell'utente relative al consenso (a condizione che la versione 2 del TCF si applichi a questo utente). Tieni presente che con il rilascio della versione 2.2 del TCF, il comando 'getTCData' è ora deprecato.

Esempio:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback using the CONSENT_DATA_READY key on the callbackQueue.
  window.googlefc.callbackQueue.push({
    'CONSENT_DATA_READY':
    () => __tcfapi('addEventListener', 2.2, (data, success) => {
      // Do something with consent data value; this callback may be invoked
      // multiple times if user consent selections change.
    })
  });
</script>

Utilizzo delle soluzioni di Google per la gestione del consenso con il framework GPP di IAB per il CPRA

Se utilizzi soluzioni di gestione del consenso di Google per raccogliere la disattivazione CPRA nell'ambito del framework GPP di IAB, devi utilizzare l'API GPP di IAB.

Data la natura di disattivazione del regolamento CPRA, puoi utilizzare la chiave della coda di callback CONSENT_API_READY o CONSENT_DATA_READY per assicurarti che l'API IAB GPP sia richiamabile e restituisca i dati del consenso quando vengono richiamati i callback.

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  window.googlefc.callbackQueue.push({
    'CONSENT_DATA_READY':
    () => __uspapi('getUSPData', 1, (data, success) => {
      // Do something with consent data value.
    })
  });
</script>

Utilizzo delle soluzioni di Google per la gestione del consenso con il framework GPP di IAB per il CPRA con un link Non vendere personalizzato

Se utilizzi soluzioni di gestione del consenso di Google per raccogliere la disattivazione CPRA nell'ambito del framework GPP di IAB, puoi fornire un link Non vendere personalizzato impostando il flag googlefc.ccpa.overrideDnsLink su true.

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Signals that the default DNS link will be overridden.
  window.googlefc.ccpa.overrideDnsLink = true;

  // Register the callback for the initial CPRA data.
  window.googlefc.callbackQueue.push({
      'INITIAL_CCPA_DATA_READY': () => {
        if (googlefc.ccpa.getInitialCcpaStatus() ===
            googlefc.ccpa.InitialCcpaStatusEnum.NOT_OPTED_OUT) {
          // TODO: Display custom CPRA Do Not Sell link here.
        }
      }
    });
</script>

Ciò garantisce che il link predefinito Non vendere non venga visualizzato. Tieni presente che sei responsabile del rendering del tuo link Non vendere per essere conforme al CPRA. Poi, devi gestire l'interazione dell'utente con il link Non vendere personalizzato richiamando la finestra di dialogo di conferma CPRA.

<script>
// This callback will be called with the user CPRA decision.
const ccpaCompletionCallback = (userOptedOut) => {
  if (userOptedOut) {
    // TODO: Hide custom CPRA Do Not Sell link here.
  }
}
// Invoke the CPRA confirmation dialog when the user clicks the link.
document.getElementById("your-custom-ccpa-do-not-sell-link").addEventListener(
  "click", () => googlefc.ccpa.openConfirmationDialog(ccpaCompletionCallback));
</script>