API JavaScript Privacy and Messaging

Introduction

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

  • supprimer les messages d'un utilisateur donné ;
  • interroger 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 obtenir le consentement des utilisateurs à l'aide de certains protocoles standards:

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

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

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

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

Résumés sur le terrain

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<string, function()>> | !Array<function()> | !googlefc.CallbackQueue Référence à la file d'attente de rappel pour l'exécution asynchrone de requêtes de messagerie utilisateur.
googlefc.CallbackQueue !Objet Type d'objet de la file d'attente de rappel.
googlefc.AdBlockerStatusEnum !Objet<chaîne, nombre> Énumération représentant l'état du bloqueur de publicité de l'utilisateur.
googlefc.AllowAdsStatusEnum !Objet<chaîne, nombre> Énumération représentant l'état d'autorisation de l'utilisateur.
googlefc.ccpa.InitialCcpaStatusEnum !Objet<chaîne, nombre> Énumération représentant l'état CPRA initial de l'utilisateur.
googlefc.ccpa.overrideDnsLink non défini|booléen Booléen qui peut être défini sur "true" pour utiliser un lien personnalisé "Ne pas vendre".

Récapitulatifs de la méthode

Nom Type renvoyé Définition
googlefc.showRevocationMessage() indéfinie Efface l'enregistrement de consentement et actualise le script googlefc pour afficher le message de consentement applicable à l'utilisateur.
googlefc.getAdBlockerStatus() nombre Renvoie une valeur dans le 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.
googlefc.ccpa.getInitialCcpaStatus() nombre Renvoie une valeur dans le InitialCcpaStatusEnum en fonction de l'état CPRA initial de l'utilisateur.
googlefc.ccpa.openConfirmationDialog(function(boolean)) indéfinie Ouvre la boîte de dialogue de confirmation d'autorisation CPRA si le lien "Ne pas vendre" est remplacé par défaut.

Tester et déboguer sur votre site

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

Conditions préalables :

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

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 de désactivation au CPRA), gdpr (messages de consentement sur le RGPD), monetization (messages du mur d'offres)

Voici quelques exemples d'utilisation de cette fonctionnalité pour prévisualiser sur votre site (foo.com):

  • Test du message sur le CPRA -- http://foo.com?fc=alwaysshow&fctype=ccpa
  • Tester le message 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. Elle permet de contrôler le rendu des messages sur des conditions spécifiées par l'éditeur, telles que le statut d'abonné ou l'URL de la page.

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

Par exemple, supposons que ce script figure 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 présenter le message qu'aux 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>

Les éditeurs de la version bêta fermée du mur d'offres peuvent spécifier que seul le mur d'offres doit être supprimé en fournissant un paramètre supplémentaire à message.proceed(). Ce paramètre est un Array de type googlefc.MessageTypeEnum. La seule énumération acceptée à partir d'aujourd'hui est OFFERWALL, mais d'autres types de messages pourront être ajoutés par la suite.

Exemple: Supposons que vous utilisiez la même fonction determineIfUserIsSubscriber() que ci-dessus. Voici un exemple d'utilisation de googlefc.controlledMessagingFunction pour supprimer la diffusion du mur d'offres uniquement 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 d'appels liés à la messagerie. Le seul moyen compatible pour appeler une fonction consiste à l'ajouter au callbackQueue.

Étant donné que les différents types de données sont 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.

Clés compatibles:

Nom de la clé Utilisation Latence relative
CONSENT_API_READY Les fonctions transmises à la file d'attente de rappel avec la clé CONSENT_API_READY sont exécutées lorsque les API pour les frameworks de consentement compatibles sont définies et appelables. À partir de ce moment, l'exécution de toutes les fonctions clés CONSENT_API_READY ajoutées ultérieurement est synchrone. Consultez les sections concernant les Cadres de l'IAB ci-dessous pour en savoir plus. Faibles
CONSENT_DATA_READY Les fonctions transmises à la file d'attente de rappels avec la clé CONSENT_DATA_READY sont exécutées lorsque l'utilisateur a obtenu le consentement dans un framework de consentement compatible (soit à partir d'une exécution précédente, soit après une interaction avec le message de consentement). À partir de ce moment, l'exécution de toutes les fonctions clés CONSENT_DATA_READY ajoutées ultérieurement est synchrone. Élevé
AD_BLOCK_DATA_READY Les fonctions placées dans la file d'attente de rappel avec la clé AD_BLOCK_DATA_READY sont exécutées lorsque les données de blocage des annonces deviennent disponibles dans le flux. À partir de ce moment, l'exécution de toutes les fonctions clés AD_BLOCK_DATA_READY ajoutées ultérieurement est synchrone. Élevé
INITIAL_CCPA_DATA_READY Les fonctions placées dans la file d'attente de rappel avec INITIAL_CCPA_DATA_READY sont exécutées lorsque les données CPRA deviennent disponibles dans le flux. Notez que toute requête ultérieure concernant des données sur le CPRA doit être obtenue directement en appelant l'API US Privacy (__uspapi). Moyenne

googlefc.CallbackQueue {!Object}

Résumé de la méthode:

Nom Type Paramètre Type renvoyé Rôle
push(data) nombre data: paire clé-valeur dont la clé est l'un des types de disponibilité des données et la valeur comme fonction JavaScript à exécuter. Les clés de disponibilité des données acceptées sont CONSENT_API_READY, CONSENT_DATA_READY, AD_BLOCK_DATA_READY et INITIAL_CCPA_DATA_READY. Nombre de commandes ajoutées jusqu'à présent. Renvoie la longueur actuelle du tableau. Exécute la fonction transmise, dans l'ordre où les données deviennent disponibles, puis selon 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 d'autorisation et de 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 d'autorisation et de 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 personnalisé "Ne pas vendre".

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, cette méthode renvoie toujours une liste vide 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 le champ AllowAdsStatusEnum en fonction de l'état d'autorisation des annonces. 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 InitialCcpaStatusEnum en fonction de l'état CPRA de l'utilisateur. La clé à spécifier pour cette fonction est INITIAL_CCPA_DATA_READY. Notez que toute requête ultérieure concernant des données CPRA doit être obtenue directement en appelant 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 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>

Si vous utilisez les solutions de gestion du consentement de Google pour recueillir le consentement au RGPD dans le cadre du TCF v2 de l'IAB, vous devez utiliser l'API v2 du TCF de l'IAB.

Vous pouvez utiliser CONSENT_API_READY

Clé de la file d'attente de rappel pour vous assurer que les rappels correspondants ne sont appelés que lorsque l'API TCF v2 de l'IAB est définie sur la page. Il doit être utilisé conjointement avec la commande 'addEventListener' de l'API TCF v2 de l'IAB, car il est possible que le consentement de l'utilisateur récupéré à l'aide de la commande synchrone 'getTCData' ne soit pas encore disponible.

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.0, (data, success) => {
      // Do something with consent data value; this callback may be invoked
      // multiple times as user completes consent flow.
    })
  });
</script>

Vous pouvez utiliser CONSENT_DATA_READY

Clé de file d'attente de rappel 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 l'API TCF v2 de l'IAB. Vous pouvez l'utiliser avec la commande 'getTCData' pour récupérer l'état du consentement de l'utilisateur à l'aide de méthodes synchrones.

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('getTCData', 2.0, (data, success) => {
      // Do something with consent data value.
    })
  });
</script>

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

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

En raison de la nature de la désactivation de la réglementation 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 IAB GPP peut être appelée et renvoyer des 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 de l'IAB pour le CPRA avec un lien personnalisé "Ne pas vendre"

Si vous utilisez les solutions de gestion du consentement de Google pour recueillir la désactivation du CPRA en vertu du framework PPG de l'IAB, vous pouvez fournir un lien personnalisé "Ne pas vendre" en définissant l'indicateur 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 qu'il est de votre responsabilité d'afficher votre propre lien "Ne pas vendre" conformément à la loi CPRA. Vous devez ensuite gérer l'interaction de l'utilisateur avec votre lien "Ne pas vendre" personnalisé en appelant la boîte de dialogue de confirmation de 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>