API JavaScript de confidentialité et de messagerie

Introduction

Cette API fournit des outils permettant d'interagir avec les messages proposés dans l'onglet "Confidentialité et messages". Grâce cet outil, vous pouvez effectuer les opérations suivantes :

• supprimer les messages d'un utilisateur donné
• Demander l'état de blocage des annonces d'un utilisateur
• autoriser un utilisateur à révoquer son consentement (le cas échéant) ;

Vous pouvez également utiliser ces outils pour recueillir le consentement des utilisateurs à l'aide de certains protocoles standards dans l'industrie:

• Consentement RGPD à l'aide de la spécification de la version 2 du TCF de l'IAB
• Désactiver la fonctionnalité CPRA en suivant la spécification CPRA de l'IAB

Dans ce cas, l'état du consentement est communiqué via ces API.

Vous pouvez déployer cette fonctionnalité de messagerie utilisateur sur votre site de plusieurs manières:

1. Dans la plupart des cas, vous n'avez pas besoin d'ajouter de nouveaux tags. Votre tag Google Publisher Tag ou votre balise AdSense existant déploie les messages destinés aux utilisateurs une fois qu'ils sont publiés dans le produit concerné.
2. Si vous utilisez le message d'incitation à réautoriser les annonces, vous devez ajouter explicitement le tag sur le blocage des annonces à votre page. Pour en savoir plus, consultez les instructions sur l'ajout de tags dans Ad Manager et AdSense.

googlefc est l'espace de noms global que la fonctionnalité de messagerie utilisateur utilise pour son API sur le Window JavaScript.

Résumés de champs

Nom	Type	Définition
googlefc.controlledMessagingFunction	fonction(!Object)	Fonction qui détermine si un message doit être envoyé. Cette fonctionnalité est compatible avec tous les types de messages.
googlefc.callbackQueue	!Array<!Object<chaîne, function()>> | !Array<function()> | !googlefc.CallbackQueue	Référence à la file d'attente de rappel pour l'exécution asynchrone des requêtes de messagerie des utilisateurs.
googlefc.CallbackQueue	!Objet	Type de l'objet de file d'attente de rappel.
googlefc.AdBlockerStatusEnum	!Object<chaîne, nombre>	Énumération représentant l'état de bloqueur de publicité de l'utilisateur.
googlefc.AllowAdsStatusEnum	!Object<chaîne, nombre>	Énumération représentant l'état des annonces autorisées de l'utilisateur.
googlefc.ccpa.InitialCcpaStatusEnum	!Object<chaîne, nombre>	Énumération représentant l'état CPRA initial de l'utilisateur.
googlefc.ccpa.overrideDnsLink	undefined|boolean	Booléen qui peut être défini sur "true" pour utiliser un lien "Do Not Sell" personnalisé.

Résumés des méthodes

Nom	Type renvoyé	Définition
googlefc.showRevocationMessage()	undefined	Efface l'enregistrement du consentement et actualise le script googlefc pour afficher le message de consentement applicable à l'utilisateur.
googlefc.getAdBlockerStatus()	Nombre	Renvoie une valeur dans AdBlockerStatusEnum en fonction de l'état de blocage des annonces de l'utilisateur.
googlefc.getAllowAdsStatus()	Nombre	Renvoie une valeur dans AllowAdsStatusEnum en fonction de l'état d'autorisation des annonces de l'utilisateur.
googlefc.ccpa.getInitialCcpaStatus()	Nombre	Renvoie une valeur dans le champ InitialCcpaStatusEnum en fonction de l'état CPRA initial de l'utilisateur.
googlefc.ccpa.openConfirmationDialog(function(boolean))	undefined	Ouvre la boîte de dialogue de confirmation concernant le CPRA si le lien "Ne pas vendre" par défaut est ignoré.

Tester et déboguer votre site

L'outil Confidentialité et messages fournit des fonctionnalités de débogage et de test qui vous permettent de voir à quoi ressemblent des messages spécifiques (ou des combinaisons de messages) sur votre site.

Conditions préalables :

• Le ou les messages que vous souhaitez prévisualiser doivent être publiés sous le site sur lequel vous effectuez le test

Vous pouvez afficher un aperçu en direct sur votre site à l'aide des paramètres d'URL de débogage suivants:

Paramètre de débogage	Valeurs autorisées
fc	alwaysshow (pour déclencher le mode débogage/aperçu)
fctype	ab (messages sur le blocage des annonces), ccpa (messages sur la désactivation du CPRA), gdpr (messages de consentement RGPD), monetization (messages Offerwall)

Voici quelques exemples d'utilisation de cette option pour afficher un aperçu sur votre site (foo.com):

• Tester l'argumentaire sur le CPRA – http://foo.com/?fc=alwaysshow&fctype=ccpa
• Tester l'argumentaire sur le RGPD – http://foo.com/?fc=alwaysshow&fctype=gdpr

Champs: explications et exemples

googlefc.controlledMessagingFunction {function(!Object)}

Fonction qui détermine si les messages doivent s'afficher ou non. Il peut servir à contrôler l'affichage des messages en fonction de conditions spécifiées par l'éditeur, telles que l'état de l'abonné ou l'URL de la page.

Lorsque vous définissez googlefc.controlledMessagingFunction sur la fenêtre avant le chargement d'autres scripts, les messages ne s'affichent pas tant que vous n'appelez pas message.proceed(boolean). L'appel de message.proceed(true) permet de poursuivre la messagerie, tandis que l'appel de message.proceed(false) empêche l'affichage de messages pour la page vue.

Exemple: Supposons que ce script se trouve sur la page qui définit une fonction asynchrone determineIfUserIsSubscriber() qui vérifie si l'utilisateur connecté est un abonné.

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

Voici un exemple d'utilisation de googlefc.controlledMessagingFunction pour ne diffuser le message qu'auprès des non-abonnés.

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

Une extension de cette fonctionnalité permet également aux éditeurs qui participent à la version bêta fermée des Offerwalls de spécifier que seul le message Offerwall doit être supprimé. Les autres types de messages ne sont pas affectés lorsque cette fonctionnalité est activée.

Les messages contrôlés spécifiques aux Offerwalls sont obtenus en transmettant un paramètre supplémentaire à message.proceed(), une Array de type googlefc.MessageTypeEnum.

Exemple: Voici un exemple d'utilisation de googlefc.controlledMessagingFunction pour supprimer uniquement la diffusion d'Offerwall pour les abonnés, sans supprimer les autres types de messages:

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

Référence à la file d'attente de rappel globale pour l'exécution asynchrone des appels liés à la messagerie. Le seul moyen accepté d'appeler une fonction consiste à l'ajouter à callbackQueue.

Étant donné que différents types de données deviennent disponibles à différents moments, une fonction doit être ajoutée en tant que mappage, avec l'une des chaînes suivantes comme clé et la fonction à exécuter comme valeur.

Clés compatibles:

Nom de la clé	Utilisation	Latence relative
CONSENT_API_READY	Les fonctions envoyées à la file d'attente de rappel avec la clé CONSENT_API_READY sont exécutées lorsque les API des frameworks de consentement compatibles sont définies et appelées. À partir de ce moment, l'exécution de toute fonction utilisant la clé CONSENT_API_READY ajoutée par la suite est synchrone. Pour en savoir plus, consultez les sections sur les frameworks de l'IAB.	Faible
CONSENT_DATA_READY	Les fonctions envoyées à la file d'attente de rappel avec la clé CONSENT_DATA_READY sont exécutées lorsque le consentement de l'utilisateur recueilli dans le cadre d'un framework de consentement compatible est connu (soit lors d'une exécution précédente, soit lorsque l'utilisateur a interagi avec le message de consentement). À partir de ce moment, l'exécution de toute fonction utilisant la clé CONSENT_DATA_READY ajoutée par la suite est synchrone.	Élevée
AD_BLOCK_DATA_READY	Les fonctions envoyées à la file d'attente de rappel avec la clé AD_BLOCK_DATA_READY sont exécutées lorsque des données sur le blocage des annonces deviennent disponibles dans le flux. À partir de ce moment, l'exécution de toute fonction utilisant la clé AD_BLOCK_DATA_READY ajoutée par la suite est synchrone.	Élevée
INITIAL_CCPA_DATA_READY	Les fonctions envoyées à la file d'attente de rappel avec INITIAL_CCPA_DATA_READY sont exécutées lorsque des données CPRA deviennent disponibles dans le flux. Notez que toute demande ultérieure de données sur le CPRA doit être obtenue en appelant directement l'API US Privacy (__uspapi).	Moyenne

---

googlefc.CallbackQueue {!Object}

Résumé de la méthode:

Nom	Type	Paramètres	Type renvoyé	Rôle
push(data)	Nombre	data: paire clé-valeur avec la clé comme l'un des types de disponibilité des données et la valeur en tant que fonction JavaScript à exécuter. Les clés de disponibilité des données acceptables sont CONSENT_API_READY, CONSENT_DATA_READY, AD_BLOCK_DATA_READY et INITIAL_CCPA_DATA_READY.	Nombre de commandes ajoutées jusqu'à présent. Cela renvoie la longueur actuelle du tableau.	Exécute la fonction transmise, dans l'ordre dans lequel les données deviennent disponibles, puis dans l'ordre dans lequel ces fonctions sont ajoutées à la file d'attente.

Exemple :

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

Représente les différents états de blocage des annonces de l'utilisateur. Les différents états sont les suivants:

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

Représente les différents états autorisés pour le blocage des annonces de l'utilisateur. Les différents états sont les suivants:

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

Représente les différents états autorisés pour le blocage des annonces de l'utilisateur. Les différents états sont les suivants:

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}

Définissez ce champ sur "true" pour masquer le lien "Ne pas vendre" par défaut et utiliser un lien "Ne pas vendre" personnalisé.

Exemple :

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

Méthodes: explications et exemples

googlefc.getConsentStatus(): {number}

---

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

1. Désormais, une liste vide est toujours renvoyée lorsqu'elle est appelée.

---

googlefc.showRevocationMessage(): {undefined}

Efface l'enregistrement de consentement actuel et affiche le message de consentement applicable à cet utilisateur. La clé à spécifier pour cette fonction est CONSENT_DATA_READY.

Exemple :

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

---

googlefc.getAdBlockerStatus(): {number}

Renvoie une valeur dans AdBlockerStatusEnum en fonction de l'état de blocage des annonces de l'utilisateur. La clé à spécifier pour cette fonction est AD_BLOCK_DATA_READY.

Exemple :

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

Renvoie une valeur dans AllowAdsStatusEnum en fonction de l'état d'autorisation des annonces de l'utilisateur. La clé à spécifier pour cette fonction est AD_BLOCK_DATA_READY.

Exemple :

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

Renvoie une valeur dans le champ InitialCcpaStatusEnum en fonction de l'état de l'utilisateur vis-à-vis de la loi CPRA. La clé à spécifier pour cette fonction est INITIAL_CCPA_DATA_READY. Notez que toute demande ultérieure de données sur le CPRA doit être obtenue en appelant directement l'API US Privacy (__uspapi).

Exemple :

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

Ouvre la boîte de dialogue de confirmation CPRA si le lien "Ne pas vendre" par défaut est ignoré. Une fois que l'utilisateur a interagi avec la boîte de dialogue de confirmation, la fonction de rappel fournie est appelée avec true si l'utilisateur décide de la désactiver, et avec false dans le cas contraire.

Exemple :

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

Utiliser les solutions de gestion du consentement de Google avec la version 2 du TCF de l'IAB pour le RGPD

Si vous utilisez des solutions de gestion du consentement de Google pour recueillir le consentement lié au RGPD dans le cadre de la version 2 du TCF de l'IAB, vous devez utiliser l'API du TCF v2 de l'IAB.

Vous pouvez utiliser la clé de file d'attente de rappel CONSENT_API_READY pour vous assurer que les rappels correspondants ne sont appelés que lorsque l'API du TCF v2 de l'IAB est définie sur la page. Elle doit être utilisée conjointement avec la commande 'addEventListener' de l'API TCF v2 de l'IAB.

Exemple :

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

Vous pouvez utiliser la clé de file d'attente de rappels CONSENT_DATA_READY pour vous assurer que les rappels correspondants ne sont appelés que lorsque le consentement de l'utilisateur est collecté et accessible à l'aide de la version 2 de l'API du TCF de l'IAB. Vous pouvez l'utiliser avec la commande 'addEventListener'. Les données fournies lors du premier appel du rappel fourni contiendront les choix de consentement de l'utilisateur (tant que la version 2 du TCF s'applique à cet utilisateur). Notez qu'avec la sortie de la version 2.2 du TCF, la commande 'getTCData' est désormais obsolète.

Exemple :

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

Utiliser les solutions de gestion du consentement de Google avec le framework GPP de l'IAB pour le CPRA

Si vous utilisez des solutions de gestion du consentement de Google pour activer la désactivation du CPRA conformément au framework GPP de l'IAB, vous devez utiliser l'API GPP de l'IAB.

En raison de la nature de la désactivation par le CPRA, vous pouvez utiliser la clé de file d'attente de rappel CONSENT_API_READY ou CONSENT_DATA_READY pour vous assurer que l'API GPP de l'IAB peut être appelée et renvoie les données de consentement au moment de l'appel des rappels.

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

Utiliser les solutions de gestion du consentement de Google avec le framework GPP de l'IAB pour le CPRA et un lien "Ne pas vendre" personnalisé

Si vous utilisez des solutions de gestion du consentement de Google pour activer la désactivation du CPRA conformément au framework GPP de l'IAB, vous pouvez fournir un lien "Ne pas vendre" personnalisé en définissant l'option googlefc.ccpa.overrideDnsLink sur 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>

Cela garantit que le lien "Ne pas vendre" par défaut ne s'affiche pas. Notez que vous êtes tenu d'afficher votre propre lien "Ne pas vendre" conformément au CPRA. Vous devez ensuite gérer l'interaction utilisateur avec votre lien personnalisé "Ne pas vendre" en appelant la boîte de dialogue de confirmation 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>