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 él, puedes realizar las siguientes tareas:

  • suprimir los mensajes para un usuario determinado
  • consultar el estado de bloqueo de anuncios de un usuario
  • permitir que un usuario revoque su 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.

Puedes implementar esta función de mensajería al usuario en tu sitio de las siguientes dos maneras:

  1. En la mayoría de los casos, no necesitas volver a etiquetar en absoluto. Tu Google Publisher Tag o la etiqueta de AdSense existentes implementa los mensajes para los usuarios una vez que el mensaje se publica en el producto relevante.
  2. Si usas el mensaje de recuperación de bloqueo de anuncios, debes agregar explícitamente la etiqueta de bloqueo de anuncios a tu página. 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 función de mensajería del usuario para su API en el Window de JavaScript.

Resúmenes de campos

Nombre Tipo Definición
googlefc.controlledMessagingFunction función(!Objeto) Una función que determina si se debe continuar con algún mensaje. Esta función 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 del objeto de cola de devoluciones de llamada.
googlefc.AdBlockerStatusEnum !Objeto<cadena, número> Una enumeración que representa el estado del bloqueador de anuncios del usuario.
googlefc.AllowAdsStatusEnum !Objeto<cadena, número> Una enumeración que representa el estado de usuarios que permitieron anuncios.
googlefc.ccpa.InitialCcpaStatusEnum !Objeto<cadena, número> Una enumeración que representa el estado inicial de la CPRA del usuario
googlefc.ccpa.overrideDnsLink undefined|boolean Valor booleano que se puede configurar como verdadero para usar un vínculo personalizado No vender

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 de 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 permitir anuncios del usuario.
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 No vender.

Prueba y depuración en tu sitio

La herramienta Privacidad y mensajería proporciona funciones de depuración y 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 sobre el que estás realizando la prueba.

Puedes obtener una vista previa en vivo en tu sitio mediante 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 o vista previa)
fctype ab (Mensajes de bloqueo de anuncios), ccpa (mensajes de inhabilitación de la CPRA), gdpr (mensajes de consentimiento del GDPR), monetization (mensajes del muro de ofertas)

Estos son algunos ejemplos de cómo usar esto para obtener una vista previa en tu sitio (foo.com):

  • Prueba los mensajes de la CPRA -- http://foo.com/?fc=alwaysshow&fctype=ccpa
  • Prueba la mensajería 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 los mensajes. Se puede usar para restringir la renderización de mensajes en condiciones especificadas por el publicador, como el estado del suscriptor o la URL de la página.

Cuando defines googlefc.controlledMessagingFunction en Window 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 como de costumbre, mientras que llamar a message.proceed(false) evita que se muestren mensajes para la vista de página.

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ó es suscriptor.

<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 podrías usar 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>

También hay una extensión de esta función que permite a los publicadores que forman parte de la versión beta cerrada de Offerwall especificar que solo se debe suprimir el Offerwall. Los demás tipos de mensajes no se ven afectados cuando esta función está activa.

Para lograr la mensajería controlada específica del Offerwall, se pasa un parámetro adicional a message.proceed(), un Array de tipo googlefc.MessageTypeEnum.

Ejemplo: Este es un ejemplo del uso de googlefc.controlledMessagingFunction a fin de suprimir solo la publicación de Offerwall 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 distintos momentos, se debe agregar una función como un mapa, con una de las siguientes cadenas 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 enviadas a la cola de devolución de llamada con la clave CONSENT_API_READY se ejecutan cuando se definen las APIs para los frameworks de consentimiento compatibles y se puede llamar a ellas. A partir de este momento, la ejecución de cualquier función con clave CONSENT_API_READY que se agregue posteriormente es síncrona. Consulta las secciones sobre los marcos de trabajo de IAB para obtener detalles específicos del framework. Baja
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 recopilado en un framework 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 cualquier función con clave CONSENT_DATA_READY que se agregue posteriormente es síncrona. Alta
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 cualquier función con clave AD_BLOCK_DATA_READY que se agregue posteriormente es síncrona. Alta
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 posterior de datos de la CPRA se debe obtener llamando directamente a la API de privacidad de EE.UU. (__uspapi). Media

googlefc.CallbackQueue {!Object}

Resumen del método:

Nombre Tipo Parámetro 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 una 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. La cantidad de comandos agregados hasta el momento. Se muestra la longitud actual del array. Ejecuta la función que se pasó, en el orden en que los datos están disponibles y, luego, según el orden en el que estas funciones se agregan 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 permisos de anuncios 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 permisos de anuncios 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 uno personalizado.

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 que se aplica a este usuario. La clave que debe especificarse 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 debe especificarse 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 permisos de anuncios del usuario. La clave que debe especificarse 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 debe especificarse para esta función es INITIAL_CCPA_DATA_READY. Ten en cuenta que cualquier solicitud posterior de datos de la CPRA debe obtenerse 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 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 inhabilitar la opción, o bien con false en caso contrario.

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

Puedes usar la clave de cola de devolución de llamada CONSENT_API_READY para asegurarte de que se invoquen las devoluciones de llamada correspondientes solo cuando se defina la API de la versión 2 del MTC de IAB en la página. Debe usarse junto con el comando 'addEventListener' de la API del MTC v2 de IAB.

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

Puedes usar la clave de cola de devolución de llamada CONSENT_DATA_READY para asegurarte de que se invoquen las devoluciones de llamada correspondientes solo cuando se recopile el consentimiento del usuario y se pueda acceder a él mediante la API del MTC v2 de IAB. Se puede usar junto con el comando 'addEventListener'. Los datos proporcionados en la primera invocación de la devolución de llamada proporcionada contendrán las selecciones de consentimiento del usuario (siempre y cuando el MTC v2 se aplique a este usuario). Ten en cuenta que, con el lanzamiento del MTC v2.2, el comando 'getTCData' dejó de estar 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_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>

Cómo usar las soluciones de administración del 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 inhabilitación de la CPRA en el marco de trabajo de la GPP de IAB, debes usar la API de la GPP de IAB.

Debido a la naturaleza de inhabilitación de la reglamentación de la CPRA, puedes usar la clave de cola 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 que muestre 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 las soluciones de administración de consentimiento de Google con el marco de trabajo de GPP de IAB para la CPRA con un vínculo personalizado de No vender

Si usas soluciones de administración de consentimiento de Google para recopilar la inhabilitación de la CPRA en el marco de trabajo de la GPP de IAB, es posible proporcionar un vínculo de No vender personalizado. Para ello, establece 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 No vender. Ten en cuenta que eres responsable de renderizar tu propio vínculo de No vender para cumplir con la CPRA. Luego, debes controlar la interacción del usuario con tu vínculo personalizado No vender 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>