API de JavaScript de privacidad y mensajería

Introducción

Esta API proporciona herramientas para interactuar con los mensajes que ofrece la pestaña Privacidad y mensajería. Con ella, puedes realizar las siguientes tareas:

  • suprimir mensajes para cualquier usuario
  • consultar el estado de bloqueo de anuncios de un usuario
  • permitir que un usuario revoque el consentimiento (si corresponde)

También puedes usar estas herramientas para obtener el consentimiento del usuario mediante algunos protocolos estándar de la industria:

En estos casos, el estado de consentimiento se comunica a través de esas APIs.

Existen varias maneras de implementar esta función de mensajería para los usuarios en tu sitio:

  1. En la mayoría de los casos, no es necesario volver a etiquetar; tu etiqueta de publicador de Google o la etiqueta de AdSense existente implementan los mensajes del usuario una vez que se publicaron en el producto relevante.
  2. Si utilizas el mensaje de recuperación de bloqueo de anuncios, debes agregar la etiqueta de bloqueo de anuncios a tu página de forma explícita. Consulta las instrucciones de etiquetado de Ad Manager y AdSense para obtener más información.

googlefc es el espacio de nombres global que usa la funcionalidad de mensajería del usuario para su API en la Window de JavaScript.

Resúmenes de campo

Nombre Tipo Definición
googlefc.controlledMessagingFunction Function(!Object) Una función que determina si se deben continuar los mensajes. Esta funcionalidad es compatible con todos los tipos de mensajes.
googlefc.callbackQueue !Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue Referencia a la cola de devolución de llamada para la ejecución asíncrona de consultas de mensajes de usuarios.
googlefc.CallbackQueue Objeto El tipo de objeto de cola de devolución de llamada.
googlefc.AdBlockerStatusEnum !Object<string, number> Una enumeración para representar el estado del bloqueador de anuncios del usuario
googlefc.AllowAdsStatusEnum !Object<string, number> Una enumeración para representar el estado del anuncio permitido del usuario.
googlefc.ccpa.InitialCcpaStatusEnum !Object<string, number> Una enumeración que representa el estado inicial de la CPRA del usuario.
googlefc.ccpa.overrideDnsLink indefinido|booleano Un valor booleano que se puede configurar como verdadero para usar un vínculo No vender personalizado

Resúmenes de métodos

Nombre Tipo de datos que se muestra Definición
googlefc.showRevocationMessage() indefinido Borra el registro de consentimiento y vuelve a cargar la secuencia de comandos googlefc para mostrar el mensaje de consentimiento aplicable al usuario.
googlefc.getAdBlockerStatus() número Muestra un valor en AdBlockerStatusEnum según el estado de bloqueo de anuncios del usuario.
googlefc.getAllowAdsStatus() número Muestra un valor en AllowAdsStatusEnum según el estado de usuarios que permiten anuncios.
googlefc.ccpa.getInitialCcpaStatus() número Muestra un valor en InitialCcpaStatusEnum según el estado inicial de la CPRA del usuario.
googlefc.ccpa.openConfirmationDialog(function(boolean)) indefinido Abre el diálogo de confirmación de la CPRA si se anula el vínculo predeterminado de No vender.

Pruebas y depuración en tu sitio

Privacidad y mensajería proporciona funciones de depuración y de prueba que te permiten ver cómo se ven los mensajes específicos (o combinaciones de mensajes) en tu sitio real.

Requisitos previos:

  • Los mensajes de los que quieres obtener una vista previa deben estar publicados en el sitio en el que realizas la prueba

Puedes obtener una vista previa en vivo en tu sitio con los siguientes parámetros de URL de depuración:

Parámetro de depuración Valores permitidos
fc alwaysshow (para activar el modo de depuración/vista previa)
fctype ab (mensajes de bloqueo de anuncios), ccpa (mensajes de inhabilitación de la CPRA), gdpr (mensajes de consentimiento del GDPR) y monetization (mensajes del muro de ofertas)

Estos son algunos ejemplos de cómo usar esta función para obtener una vista previa en su sitio (foo.com):

  • Mensaje de la CPRA de prueba: http://foo.com?fc=alwaysshow&fctype=ccpa
  • Pruebe los mensajes del GDPR: http://foo.com?fc=alwaysshow&fctype=gdpr

Campos: explicaciones y ejemplos

googlefc.controlledMessagingFunction {function(!Object)}

Una función que determina si se deben mostrar o no los mensajes. Se puede usar para limitar la renderización de mensajes en condiciones especificadas por el editor, como el estado de suscriptor o la URL de la página.

Cuando defines googlefc.controlledMessagingFunction en la ventana antes de que se carguen otras secuencias de comandos, los mensajes no se muestran hasta que llamas a message.proceed(boolean). Llamar a message.proceed(true) permite que los mensajes continúen de la manera habitual, mientras que llamar a message.proceed(false) evita que se muestren mensajes para la página vista.

Ejemplo: Supongamos que tienes esta secuencia de comandos en la página, que define una función asíncrona determineIfUserIsSubscriber() que verifica si el usuario que accedió está suscrito.

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

Este es un ejemplo de cómo puedes usar el googlefc.controlledMessagingFunction para mostrar el mensaje solo a los usuarios no suscritos.

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

Los editores que forman parte de la versión beta cerrada de Offerwall pueden especificar que solo se debe eliminar el muro de ofertas mediante el suministro de un parámetro adicional a message.proceed(). Este parámetro es un Array de tipo googlefc.MessageTypeEnum. La única enumeración admitida hoy es OFFERWALL, pero se pueden agregar tipos de mensajes adicionales en el futuro.

Ejemplo: Supongamos que tienes la misma función determineIfUserIsSubscriber() que la anterior. En este ejemplo, se usa googlefc.controlledMessagingFunction a fin de únicamente suprimir la publicación de ofertas para los suscriptores, sin suprimir otros tipos de mensajes:

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

Referencia a la cola de devolución de llamada global para la ejecución asíncrona de llamadas relacionadas con la mensajería. La única forma admitida para invocar cualquier función es agregarla a callbackQueue.

Dado que diferentes tipos de datos están disponibles en momentos diferentes, se debe agregar una función como un mapa, con una de las siguientes strings como clave y la función que se ejecutará como valor.

Claves admitidas:

Nombre de la clave Uso Latencia relativa
CONSENT_API_READY Las funciones que se envían a la cola de devolución de llamada con la clave CONSENT_API_READY se ejecutan cuando se definen las API para frameworks de consentimiento compatibles y se pueden llamar a ellas. A partir de este momento, la ejecución de las funciones con clave CONSENT_API_READY que se agreguen posteriormente es síncrona. Consulta las secciones sobre los marcos de trabajo de la IAB a continuación para obtener detalles específicos del marco de trabajo. Bajo
CONSENT_DATA_READY Las funciones enviadas a la cola de devoluciones de llamada con la clave CONSENT_DATA_READY se ejecutan cuando se conoce el consentimiento del usuario obtenido en un marco de trabajo de consentimiento compatible (ya sea de una ejecución anterior o una vez que el usuario interactúa con el mensaje de consentimiento). A partir de este momento, la ejecución de las funciones con clave CONSENT_DATA_READY que se agreguen posteriormente es síncrona. Alto
AD_BLOCK_DATA_READY Las funciones enviadas a la cola de devolución de llamada con la clave AD_BLOCK_DATA_READY se ejecutan cuando los datos de bloqueo de anuncios están disponibles en el flujo. A partir de este momento, la ejecución de las funciones con clave AD_BLOCK_DATA_READY que se agreguen posteriormente es síncrona. Alto
INITIAL_CCPA_DATA_READY Las funciones enviadas a la cola de devolución de llamada con el INITIAL_CCPA_DATA_READY se ejecutan cuando los datos de la CPRA están disponibles en el flujo. Ten en cuenta que cualquier solicitud de datos de la CPRA posterior se debe obtener llamando directamente a la API de privacidad de EE.UU. (__uspapi). Media

googlefc.CallbackQueue {!Object}

Resumen del método:

Nombre Tipo Parameter Tipo de datos que se muestra Rol
push(data) número data: Es un par clave-valor con la clave como uno de los tipos de disponibilidad de datos y el valor como función de JavaScript que se ejecutará. Las claves de disponibilidad de datos aceptables son CONSENT_API_READY, CONSENT_DATA_READY, AD_BLOCK_DATA_READY y INITIAL_CCPA_DATA_READY. Es la cantidad de comandos agregados hasta el momento. Esto muestra la longitud actual del array. Ejecuta la función pasada, en el orden en que los datos están disponibles, y por el orden en que se agregan estas funciones a la cola.

Ejemplo:

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

Representa los diferentes estados de bloqueo de anuncios del usuario. Los diferentes estados son los siguientes:

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

Representa los diferentes estados de permiso de bloqueo de anuncios del usuario. Los diferentes estados son los siguientes:

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

Representa los diferentes estados de permiso de bloqueo de anuncios del usuario. Los diferentes estados son los siguientes:

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}

Establece este campo en verdadero para ocultar el vínculo predeterminado No vender y usar un vínculo personalizado No vender.

Ejemplo:

<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étodos: explicaciones y ejemplos

googlefc.getConsentStatus(): {number}


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

  1. Ahora siempre muestra una lista vacía cuando se la llama.

googlefc.showRevocationMessage(): {undefined}

Borra el registro de consentimiento actual y muestra el mensaje de consentimiento aplicable a este usuario. La clave que se debe especificar para esta función es CONSENT_DATA_READY.

Ejemplo:

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

googlefc.getAdBlockerStatus(): {number}

Muestra un valor en AdBlockerStatusEnum según el estado de bloqueo de anuncios del usuario. La clave que se debe especificar para esta función es AD_BLOCK_DATA_READY.

Ejemplo:

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

Muestra un valor en AllowAdsStatusEnum según el estado de usuarios que permiten anuncios. La clave que se debe especificar para esta función es AD_BLOCK_DATA_READY.

Ejemplo:

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

Muestra un valor en InitialCcpaStatusEnum según el estado de la CPRA del usuario. La clave que se debe especificar para esta función es INITIAL_CCPA_DATA_READY. Ten en cuenta que cualquier solicitud posterior de datos de la CPRA se debe obtener llamando directamente a la API de privacidad de EE.UU. (__uspapi).

Ejemplo:

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

Abre el diálogo de confirmación de la CPRA si se anula el vínculo predeterminado de No vender. Una vez que el usuario interactúa con el diálogo de confirmación, se llama a la función de devolución de llamada proporcionada con true si el usuario decide rechazar esta acción y, de lo contrario, se llama a false.

Ejemplo:

<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 usas soluciones de administración de consentimiento de Google para obtener el consentimiento del GDPR según el marco de trabajo del MTC v2 de IAB, debes usar la API del MTC v2 de IAB.

Puedes usar CONSENT_API_READY

. Debe usarse junto con el comando 'addEventListener' de la API del MTC v2 de IAB, ya que es posible que el consentimiento del usuario recuperado mediante el comando síncrono 'getTCData' aún no esté disponible.

Ejemplo:

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

Puedes usar CONSENT_DATA_READY

. Se puede usar junto con el comando 'getTCData', ya que puedes recuperar el estado de consentimiento del usuario mediante métodos síncronos.

Ejemplo:

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

Usa soluciones de administración de consentimiento de Google con el marco de trabajo de GPP de IAB para la CPRA

Si usas soluciones de administración de consentimiento de Google para recopilar la opción de inhabilitación de la CPRA en virtud del marco de trabajo de GPP de IAB, debes usar la API de GPP de IAB.

Debido a la naturaleza de inhabilitación de la reglamentación de la CPRA, puedes usar la clave de devolución de llamada CONSENT_API_READY o CONSENT_DATA_READY para asegurarte de que se pueda llamar a la API de GPP de IAB y se muestren datos de consentimiento en el momento en que se invocan las devoluciones de llamada.

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

Uso de soluciones de administración de consentimiento de Google con el marco de trabajo de GPP de IAB para la CPRA con un vínculo No vender personalizado

Si usas soluciones de administración de consentimiento de Google para recopilar la opción de rechazar la CPRA en el marco de trabajo de GPP de IAB, puedes proporcionar un vínculo personalizado de no vender configurando la marca googlefc.ccpa.overrideDnsLink en 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>

Esto garantiza que no se renderice el vínculo predeterminado de No vender. Ten en cuenta que eres responsable de renderizar tu propio vínculo de No vender a fin de cumplir con la CPRA. Luego, debes controlar la interacción del usuario con el vínculo No vender personalizado mediante la invocación del diálogo de confirmación de la 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>