API de JavaScript de privacidad y mensajería

Introducción

Esta API proporciona herramientas para interactuar con los mensajes que ofrece el Privacy & mensajes. Con él, 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 de los usuarios con algunos estándares de la industria protocolos:

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

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

  1. En la mayoría de los casos, no necesitas volver a etiquetarlo, ya que tu cuenta de Google Publicador Etiqueta o Implementaciones de etiquetas de AdSense los mensajes de 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 el anuncio bloqueando explícitamente la etiqueta en tu página. Ver anuncio Administrador y Etiquetado de AdSense instrucciones para obtener más información.

googlefc es el espacio de nombres global que usa la función de mensajería de los usuarios. para su API en JavaScript Window.

Resúmenes de campos

Nombre Tipo Definición
googlefc.controlledMessagingFunction función(!Objeto) Una función que determina si se debe continuar con cualquier mensaje Esta función es compatible con todos los tipos de mensajes.
googlefc.callbackQueue !Array<!Object<string, function()>> | !Array&lt;function()&gt; | !googlefc.CallbackQueue Referencia a la cola de devolución de llamada para la ejecución asíncrona de las consultas de mensajería de los usuarios.
googlefc.CallbackQueue !Object El tipo de objeto de la cola de devolución de llamada.
googlefc.AdBlockerStatusEnum !Object<string, número> Una enumeración para representar el estado del bloqueador de anuncios del usuario.
googlefc.AllowAdsStatusEnum !Object<string, número> Una enumeración para representar el estado de permisos de anuncios del usuario.
googlefc.ccpa.InitialCcpaStatusEnum !Object<string, número> Una enumeración para representar el estado inicial de la CPRA del usuario.
googlefc.ccpa.overrideDnsLink indefinido|booleano Booleano que se puede configurar como verdadero para usar un vínculo personalizado de 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 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 permiso de 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.

Cómo realizar pruebas y depuraciones en tu sitio

Privacidad y La mensajería proporciona la funcionalidad de depuración y prueba que te permite para ver el aspecto de mensajes específicos (o combinaciones de mensajes) en tu el sitio en cuestión.

Requisitos previos:

  • Los mensajes de los que quieras obtener una vista previa deben estar publicados en el sitio del que estás pruebas contra

Puedes obtener una vista previa en vivo en tu sitio mediante la siguiente URL de depuración parámetros:

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), monetization (mensajes de Offerwall)

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

  • Mensaje de la CPRA de prueba -- http://foo.com/?fc=alwaysshow&fctype=ccpa
  • Probar 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 los mensajes se deben mostrar o no. Sí, es posible que se usa para impedir la renderización de mensajes en condiciones especificadas por el publicador, como el estado del suscriptor o la URL de la página.

Si defines googlefc.controlledMessagingFunction en la ventana antes de cargando otras secuencias de comandos, los mensajes no aparecen hasta que llames message.proceed(boolean) Llamar a message.proceed(true) permite enviar mensajes a procede como de costumbre, mientras que llamar a message.proceed(false) evita que se envíen mensajes para que no se muestre para la vista de página.

Ejemplo: supongamos que tienes esta secuencia de comandos en la página que define un modelo de función determineIfUserIsSubscriber() que verifica si el usuario que accedió es un 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 la googlefc.controlledMessagingFunction para mostrarle el mensaje solo a 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 que los editores la versión beta cerrada del Offerwall para especificar que solo se debe se suprimió. Otros tipos de mensajes no se ven afectados cuando esta función está activa.

Los mensajes controlados específicos del Offerwall se logran pasando un mensaje parámetro en message.proceed(), un Array de tipo googlefc.MessageTypeEnum.

Ejemplo: Este es un ejemplo de cómo usar googlefc.controlledMessagingFunction para solo suprimir la entrega del 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 mediante agregarlo a callbackQueue.

Dado que diferentes tipos de datos están disponibles en diferentes momentos, una función debe agregarse como mapa, con una de las siguientes cadenas como clave y el función se ejecute como el 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 admiten llamadas. 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 IAB para obtener detalles específicos sobre los marcos de trabajo. Bajo
CONSENT_DATA_READY Las funciones enviadas a la cola de devolución 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úe 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. 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 hay datos de bloqueo de anuncios 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. 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). Medio

googlefc.CallbackQueue {!Object}

Resumen del método:

Nombre Tipo Parámetro Tipo de datos que se muestra Rol
push(data) número data: Un par clave-valor con la clave como uno de los datos disponibilidad 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 ahora. Esto muestra la longitud actual del array. Ejecuta la función pasada, en el orden en que los datos se convierten disponibles, luego, por el orden en el que estas funciones se agregan al en la fila.

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:

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 bloqueo de anuncios del usuario. La diferencia estados son:

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 bloqueo de anuncios del usuario. La diferencia estados son:

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}

Configura este campo como 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 que se que se aplica 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}

Devuelve 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 permiso de anuncios de 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.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}

Devuelve un valor en InitialCcpaStatusEnum según el estado de la CPRA de del usuario. La clave que se debe especificar para esta función es INITIAL_CCPA_DATA_READY Ten en cuenta que todas las solicitudes posteriores de datos de la CPRA deben 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 el vínculo No vender predeterminado es anulada. Una vez que el usuario interactúe con el cuadro de diálogo de confirmación, el botón se llama a la función de devolución de llamada con true si el usuario decide inhabilitar esta opción. De lo contrario, 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 utilizas las soluciones de administración de consentimiento de Google para obtener el consentimiento según el RGPD según el MTC v2 de IAB, debes usar la versión 2 del MTC de IAB API

Puedes usar la CONSENT_API_READY de la cola de devolución de llamada para garantizar que las devoluciones de llamada correspondientes se invoquen solo cuando la API de la versión 2 del MTC de IAB se define en la página. Debe usarse en conjunto con el 'addEventListener' de la API de la versión 2 del MTC 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 CONSENT_DATA_READY para garantizar que se invoquen las devoluciones de llamada correspondientes. solo cuando se recopila el consentimiento del usuario y se puede acceder a él mediante la API de la versión 2 del MTC de IAB. Esto se puede usar junto con el 'addEventListener' comando: los datos proporcionados en la primera invocación de la devolución de llamada proporcionada contendrá las selecciones de consentimiento del usuario (siempre y cuando la versión 2 del MTC se aplique a este usuario). Tenga en cuenta que, con el lanzamiento de la versión 2.2 del MTC, la 'getTCData' el comando 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>

Uso de las soluciones de administración de consentimiento de Google con el marco de GPP de IAB para la CPRA

Si usas soluciones de administración de consentimiento de Google para recopilar información sobre el rechazo de la CPRA según el marco de GPP de IAB, debe usar la GPP de IAB API

Debido a la naturaleza de exclusión de la reglamentación de la CPRA, puedes usar cualquiera de las dos opciones: CONSENT_API_READY o Devolución de llamada CONSENT_DATA_READY clave de cola para garantizar que se pueda llamar a la API de GPP de IAB y que se muestren los datos de consentimiento cuando 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 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 información sobre el rechazo de la CPRA según el marco de GPP de IAB, es posible ofrecer un vínculo personalizado de No vender estableciendo 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 son responsables de renderizar tu propio vínculo de No vender para cumplir con con la CPRA. Luego, debes controlar la interacción del usuario con tu Invoca el diálogo de confirmación de la CPRA para vender la vinculación.

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