API Privacy & Messaging JavaScript

Introdução

Essa API fornece ferramentas para interagir com mensagens oferecidas pela guia "Privacidade e mensagens". Com ele, é possível fazer muito:

  • suprimir mensagens para qualquer usuário
  • consultar o status de bloqueio de anúncios de um usuário
  • Permitir que um usuário revogue o consentimento (se aplicável)

Também é possível usar essas ferramentas para solicitar o consentimento do usuário usando alguns protocolos padrão do setor:

Nesses casos, o status de consentimento é comunicado por essas APIs.

Você pode implantar essa funcionalidade de mensagens do usuário no seu site de duas maneiras:

  1. Na maioria dos casos, você não precisa fazer novas tags. A tag do editor do Google ou a tag do Google AdSense atual implanta mensagens do usuário depois que a mensagem é publicada no produto relevante.
  2. Se você estiver usando a mensagem de recuperação de bloqueio de anúncios, será necessário adicionar a tag de bloqueio de anúncios explicitamente à sua página. Consulte as instruções de tagging do Ad Manager e do Google AdSense para mais informações.

googlefc é o namespace global que a funcionalidade de mensagens do usuário usa para a API no JavaScript Window.

Resumos de campo

Nome Tipo Definição
googlefc.controlledMessagingFunction function(!Object) Uma função que determina se continua com qualquer mensagem. Essa funcionalidade é compatível com todos os tipos de mensagem.
googlefc.callbackQueue !Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue Referência à fila de callback para execução assíncrona de consultas de mensagens do usuário.
googlefc.CallbackQueue !Objeto O tipo do objeto da fila de callback.
googlefc.AdBlockerStatusEnum !Objeto<string, número> Um enum para representar o estado do bloqueador de anúncios do usuário.
googlefc.AllowAdsStatusEnum !Objeto<string, número> Um enum para representar o estado allow-ads do usuário.
googlefc.ccpa.InitialCcpaStatusEnum !Objeto<string, número> Um enum para representar o status CPRA inicial do usuário.
googlefc.ccpa.overrideDnsLink indefinido|booleano Um booleano que pode ser definido como verdadeiro para usar um link personalizado "Não vender".

Resumos dos métodos

Nome Tipo de retorno Definição
googlefc.showRevocationMessage() indefinido Limpa o registro de consentimento e recarrega o script googlefc para mostrar a mensagem de consentimento aplicável ao usuário.
googlefc.getAdBlockerStatus() number Retorna um valor no AdBlockerStatusEnum, dependendo do status de bloqueio de anúncios do usuário.
googlefc.getAllowAdsStatus() number Retorna um valor no AllowAdsStatusEnum, dependendo do status de permissão dos anúncios do usuário.
googlefc.ccpa.getInitialCcpaStatus() number Retorna um valor no InitialCcpaStatusEnum, dependendo do status inicial da CPRA do usuário.
googlefc.ccpa.openConfirmationDialog(function(boolean)) indefinido Abre a caixa de diálogo de confirmação da CPRA se o link padrão "Não vender" for modificado.

Como testar e depurar no seu site

A seção "Privacidade e mensagens" oferece funcionalidade de depuração e teste que permite ver a aparência de mensagens específicas (ou combinações de mensagens) no seu site real.

Pré-requisitos:

  • As mensagens que você quer visualizar precisam ser publicadas no site que está sendo testado

Você pode ver uma visualização em tempo real no seu site usando os seguintes parâmetros de URL de depuração:

Parâmetro de depuração Valores permitidos
fc alwaysshow (para acionar o modo de depuração/visualização)
fctype ab (mensagens de bloqueio de anúncios), ccpa (mensagens de desativação da CPRA), gdpr (mensagens de consentimento do GDPR), monetization (mensagens do mural de ofertas)

Alguns exemplos de como usar isso para visualizar no seu site (foo.com):

  • Mensagem da CPRA de teste: http://foo.com?fc=alwaysshow&fctype=ccpa
  • Testar mensagens do GDPR: http://foo.com?fc=alwaysshow&fctype=gdpr

Campos: explicações e exemplos

googlefc.controlledMessagingFunction {function(!Object)}

Uma função que determina se as mensagens devem ou não ser exibidas. Ele pode ser usado para bloquear a renderização de mensagens nas condições especificadas pelo editor, como o status do assinante ou o URL da página.

Quando você define googlefc.controlledMessagingFunction na janela antes do carregamento de outros scripts, as mensagens não são exibidas até que você chame message.proceed(boolean). Chamar message.proceed(true) permite que a mensagem continue, enquanto chamar message.proceed(false) impede que as mensagens sejam exibidas na visualização de página.

Exemplo: suponha que você tenha esse script na página que define uma função assíncrona determineIfUserIsSubscriber() que verifica se o usuário conectado é um assinante.

<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 é um exemplo de como usar o googlefc.controlledMessagingFunction para mostrar a mensagem apenas para não inscritos.

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

Os editores que fazem parte da versão Beta fechada do mural de ofertas podem especificar que apenas o mural precisa ser suprimido fornecendo um parâmetro adicional para message.proceed(). Esse parâmetro é um Array do tipo googlefc.MessageTypeEnum. O único tipo enumerado compatível atualmente é OFFERWALL, mas outros tipos de mensagem podem ser adicionados no futuro.

Exemplo: suponha que você tenha a mesma função determineIfUserIsSubscriber() acima. Este é um exemplo de como usar googlefc.controlledMessagingFunction para suprimir apenas a exibição do mural de ofertas para assinantes, sem suprimir outros tipos de mensagem:

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

Referência à fila de callback global para execução assíncrona de chamadas relacionadas a mensagens. A única maneira compatível de invocar qualquer função é adicioná-la ao callbackQueue.

Como tipos diferentes de dados ficam disponíveis em momentos diferentes, uma função deve ser adicionada como um mapa, com uma das seguintes strings como a chave e a função a ser executada como o valor.

Chaves compatíveis:

Nome da chave Uso Latência relativa
CONSENT_API_READY As funções enviadas à fila de callback com a chave CONSENT_API_READY são executadas quando as APIs dos frameworks de consentimento compatíveis são definidas e chamáveis. Daqui em diante, a execução de qualquer função adicionada CONSENT_API_READY em seguida é síncrona. Consulte as seções sobre frameworks do IAB abaixo para detalhes específicos sobre o framework. Baixo
CONSENT_DATA_READY As funções enviadas à fila de callback com a chave CONSENT_DATA_READY são executadas quando o consentimento do usuário coletado em um framework compatível é conhecido (de uma execução anterior ou de uma interação com a mensagem de consentimento). Daqui em diante, a execução de qualquer função adicionada CONSENT_DATA_READY em seguida é síncrona. Alto
AD_BLOCK_DATA_READY As funções enviadas à fila de callback com a chave AD_BLOCK_DATA_READY são executadas quando os dados de bloqueio de anúncios são disponibilizados no fluxo. A partir desse ponto, a execução de qualquer função adicionada AD_BLOCK_DATA_READY que tenha sido adicionada depois será síncrona. Alto
INITIAL_CCPA_DATA_READY As funções enviadas à fila de callback com INITIAL_CCPA_DATA_READY são executadas quando os dados da CPRA são disponibilizados no fluxo. Qualquer solicitação subsequente de dados da CPRA precisa ser recebida chamando diretamente a API de privacidade dos EUA (__uspapi). Médio

googlefc.CallbackQueue {!Object}

Resumo do método:

Nome Tipo Parâmetro Tipo de retorno Papel
push(data) number data: um par de chave-valor com a chave como um dos tipos de disponibilidade de dados e o valor como uma função JavaScript a ser executada. As chaves de disponibilidade de dados aceitáveis são CONSENT_API_READY, CONSENT_DATA_READY, AD_BLOCK_DATA_READY e INITIAL_CCPA_DATA_READY. O número de comandos adicionados até agora. Isso retorna o comprimento atual da matriz. Executa a função transmitida, na ordem em que os dados ficam disponíveis e pela ordem em que essas funções são adicionadas à fila.

Exemplo:

<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 os diferentes estados de bloqueio de anúncios do usuário. Os diferentes estados são:

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 os diferentes estados de permissão de anúncios de bloqueio do usuário. Os diferentes estados são:

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 os diferentes estados de permissão de anúncios de bloqueio do usuário. Os diferentes estados são:

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}

Defina este campo como "true" para ocultar o link padrão "Não vender" e usar um link "Não vender" personalizado.

Exemplo:

<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: explicações e exemplos

googlefc.getConsentStatus(): {number}


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

  1. Isso agora sempre retorna uma lista vazia quando chamado.

googlefc.showRevocationMessage(): {undefined}

Limpa o registro de consentimento atual e mostra a mensagem de consentimento aplicável a esse usuário. A chave que precisa ser especificada para essa função é CONSENT_DATA_READY.

Exemplo:

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

googlefc.getAdBlockerStatus(): {number}

Retorna um valor em AdBlockerStatusEnum, dependendo do status de bloqueio de anúncios do usuário. A chave que precisa ser especificada para essa função é AD_BLOCK_DATA_READY.

Exemplo:

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

Retorna um valor no AllowAdsStatusEnum, dependendo do status de permissão dos anúncios do usuário. A chave que precisa ser especificada para essa função é AD_BLOCK_DATA_READY.

Exemplo:

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

Retorna um valor no InitialCcpaStatusEnum, dependendo do status da CPRA do usuário. A chave que precisa ser especificada para essa função é INITIAL_CCPA_DATA_READY. Qualquer solicitação subsequente de dados da CPRA precisa ser recebida chamando diretamente a API de privacidade dos EUA (__uspapi).

Exemplo:

<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 a caixa de diálogo de confirmação da CPRA se o link padrão "Não vender" for modificado. Depois que o usuário interagir com a caixa de diálogo de confirmação, a função de callback fornecida será chamada com true se o usuário decidir desativá-la. Caso contrário, ela será false.

Exemplo:

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

Se você estiver usando as soluções de gerenciamento de consentimento do Google para receber o consentimento do GDPR de acordo com o framework do TCF v2.0 do IAB, use a API TCF v2 do IAB.

Você pode usar o CONSENT_API_READY

chave de fila de callback para garantir que os callbacks correspondentes sejam invocados somente quando a API TCF v2 do IAB estiver definida na página. Isso deve ser usado em conjunto com o comando 'addEventListener' da API TCF v2 do IAB, já que o consentimento do usuário buscado com o comando 'getTCData' síncrono pode ainda não estar disponível.

Exemplo:

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

Você pode usar o CONSENT_DATA_READY

chave de fila de callback para garantir que os callbacks correspondentes sejam invocados somente quando o consentimento do usuário for coletado e acessado por meio da API TCF v2 do IAB. Isso pode ser usado em conjunto com o comando 'getTCData', já que é possível buscar o status de consentimento do usuário usando métodos síncronos.

Exemplo:

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

Como usar as soluções de gerenciamento de consentimento do Google com a estrutura GPP do IAB para a CPRA

Se você estiver usando as soluções de gerenciamento de consentimento do Google para coletar a desativação da CPRA de acordo com o framework GPP do IAB, use a API GPP do IAB.

Devido à natureza da desativação da regulamentação da CPRA, é possível usar a chave de fila de callback CONSENT_API_READY ou CONSENT_DATA_READY para garantir que a API GPP do IAB possa ser chamada e retorne dados de consentimento no momento em que os callbacks forem invocados.

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

Como usar as soluções de gerenciamento de consentimento do Google com a estrutura GPP do IAB para a CPRA com um link "Não vender" personalizado

Se você estiver usando as soluções de gerenciamento de consentimento do Google para coletar a desativação da CPRA no framework GPP do IAB, será possível fornecer um link "Não vender" personalizado definindo a sinalização googlefc.ccpa.overrideDnsLink como 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>

Isso garante que o link "Não vender" padrão não seja renderizado. Você é responsável por renderizar seu próprio link "Não vender" para estar em conformidade com a CPRA. Em seguida, é necessário processar a interação do usuário com o link "Não vender" personalizado invocando a caixa de diálogo de confirmação da 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>