API Privacy & Messaging JavaScript

Introdução

Essa API oferece ferramentas para interagir com mensagens oferecidas pela guia "Privacidade e mensagens". Ele serve para diversas coisas:

• suprimir mensagens de 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)

Você também pode usar essas ferramentas para solicitar o consentimento do usuário por meio de alguns protocolos padrão do setor:

• Consentimento do GDPR usando a especificação do TCF v2 do IAB
• Desativação da CPRA usando as especificações da CPRA de GPP do IAB

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

É possível implantar essa funcionalidade de mensagens para os usuários no seu site de algumas maneiras:

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

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

Resumos de campo

Nome	Tipo	Definição
googlefc.controlledMessagingFunction	função(!Objeto)	Uma função que determina se é necessário enviar alguma mensagem. Essa funcionalidade é compatível com todos os tipos de mensagens.
googlefc.callbackQueue	!Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue	Referência à fila de retorno de chamada 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, number>	Um enum para representar o estado de bloqueador de anúncios do usuário.
googlefc.AllowAdsStatusEnum	!Objeto<string, number>	Um enum para representar o estado allow-ads do usuário.
googlefc.ccpa.InitialCcpaStatusEnum	!Objeto<string, number>	Um enum para representar o status inicial da CPRA do usuário.
googlefc.ccpa.overrideDnsLink	undefined|boolean	Um booleano que pode ser definido como verdadeiro para usar um link personalizado "Não vender".

Resumos de 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 allow-ads 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 substituído.

Como testar e depurar seu site

A seção "Privacidade e mensagens" oferece recursos de depuração e testes que permitem conferir a aparência de mensagens específicas (ou combinações de mensagens) no seu site.

Pré-requisitos:

• As mensagens que você quer visualizar precisam ser publicadas no site em teste.

Acesse 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 Offerwall)

Alguns exemplos de como usar esse recurso na visualização no seu site (foo.com):

• Testar mensagem da CPRA: http://foo.com/?fc=alwaysshow&fctype=ccpa
• Testar a mensagem 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 serão exibidas ou não. Ele pode ser usado para bloquear a renderização de mensagens em condições especificadas pelo editor, como status de assinante ou 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 as mensagens continuem normalmente, enquanto chamar message.proceed(false) impede que qualquer mensagem seja mostrada 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 você pode 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>

Há também uma extensão desse recurso que permite que os editores parte da versão Beta fechada do Offerwall especifiquem que apenas o Offerwall vai ser suprimido. Outros tipos de mensagens não são afetados quando esse recurso está em vigor.

As mensagens controladas específicas do Offerwall são alcançadas transmitindo um outro parâmetro para message.proceed(), um Array do tipo googlefc.MessageTypeEnum.

Exemplo: este é um exemplo de uso de googlefc.controlledMessagingFunction para suprimir apenas a veiculação do Offerwall para assinantes, sem suprimir outros tipos de mensagens:

<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 é adicionando-a ao callbackQueue.

Como diferentes tipos de dados são disponibilizados em momentos distintos, adicione uma função como um mapa, com uma das strings a seguir 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 para a fila de callback com a chave CONSENT_API_READY são executadas quando as APIs de frameworks de consentimento compatíveis são definidas e chamáveis. A partir desse ponto, a execução de qualquer função com chave CONSENT_API_READY adicionada posteriormente é síncrona. Consulte as seções em Estruturas do IAB para detalhes específicos.	Baixa
CONSENT_DATA_READY	As funções enviadas para a fila de callback com a chave CONSENT_DATA_READY são executadas quando o consentimento do usuário coletado em um framework de consentimento compatível é conhecido, seja de uma execução anterior ou depois que o usuário interage com a mensagem. A partir desse ponto, a execução de qualquer função com chave CONSENT_DATA_READY adicionada posteriormente é síncrona.	Alto
AD_BLOCK_DATA_READY	As funções enviadas para a fila de callback com a chave AD_BLOCK_DATA_READY são executadas quando os dados de bloqueio de anúncios ficam disponíveis no fluxo. A partir desse ponto, a execução de qualquer função com chave AD_BLOCK_DATA_READY adicionada posteriormente é síncrona.	Alto
INITIAL_CCPA_DATA_READY	As funções enviadas para a fila de callback com o INITIAL_CCPA_DATA_READY são executadas quando os dados da CPRA ficam disponíveis no fluxo. As solicitações subsequentes de dados da CPRA precisam ser recebidas chamando diretamente a API US Privacy (__uspapi).	Média

---

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é o momento. Isso retorna o comprimento atual da matriz.	Executa a função transmitida na ordem em que os dados ficam disponíveis e, em seguida, na 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 bloqueio de anúncios 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 bloqueio de anúncios 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 esse campo como verdadeiro 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. Agora, ele sempre retorna uma lista vazia quando chamado.

---

googlefc.showRevocationMessage(): {undefined}

Limpa o registro de consentimento atual e mostra a mensagem de consentimento aplicável ao 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 no 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 allow-ads 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. As solicitações subsequentes de dados da CPRA precisam ser recebidas chamando diretamente a API US Privacy (__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 substituído. 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 desativar. Caso contrário, será usada 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>

Como usar as soluções de gestão de consentimento do Google com o TCF v2.0 do IAB para GDPR

Se você estiver usando soluções de gestão de consentimento do Google para coletar o consentimento do GDPR de acordo com a estrutura do IAB TCF v2, use a API do TCF v2.0 do IAB.

É possível usar a chave da fila de callback CONSENT_API_READY para garantir que os callbacks correspondentes sejam invocados somente quando a API TCF v2 do IAB for definida na página. Ela precisa ser usada em conjunto com o comando 'addEventListener' da API IAB TCF v2.

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

Use a chave da fila de callback CONSENT_DATA_READY para garantir que os callbacks correspondentes sejam invocados somente quando o consentimento do usuário for coletado e acessível usando a API IAB TCF v2. Isso pode ser usado em conjunto com o comando 'addEventListener': os dados fornecidos na primeira invocação do callback fornecido conterão as seleções de consentimento do usuário, desde que o TCF v2 se aplique a ele. Com o lançamento do TCF v2.2, o uso do comando 'getTCData' foi suspenso.

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('addEventListener', 2.2, (data, success) => {
      // Do something with consent data value; this callback may be invoked
      // multiple times if user consent selections change.
    })
  });
</script>

Como usar as soluções de gestão de consentimento do Google com o framework de GPP do IAB para CPRA

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

Devido à natureza de desativação do regulamento CPRA, você pode usar a chave da fila de callback CONSENT_API_READY ou CONSENT_DATA_READY para garantir que a API GPP do IAB possa ser chamada e retornar 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 gestão de consentimento do Google com o framework de GPP do IAB para CPRA com um link "Não vender" personalizado

Se você estiver usando as soluções de gestão de consentimento do Google para solicitar a desativação da CPRA no framework de GPP do IAB, poderá 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 padrão "Não vender" 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 personalizado "Não vender" 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>