API Privacy & Messaging JavaScript

Introdução

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

e mais.

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

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

É possível implantar essa funcionalidade de mensagens do usuário no seu site de algumas maneiras:

  1. Na maioria dos casos, não é necessário adicionar novas tags. A Tag de Publisher do Google ou a tag do Google AdSense que você já tem implanta as mensagens do usuário assim que elas são publicadas no produto relevante.
  2. Se você estiver usando a mensagem de resposta ao bloqueio de anúncios, precisará adicionar a tag de bloqueio de anúncios à sua página de forma explícita. Consulte as instruções de inclusão de tags do Ad Manager e do AdSense para mais informações.

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

Resumos de campos

Nome Tipo Definição
googlefc.controlledMessagingFunction function(!Object) Uma função que determina se é necessário prosseguir com as mensagens. Essa funcionalidade está disponível para 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 !Object O tipo do objeto da fila de callback.
googlefc.AdBlockerStatusEnum !Object<string, number> Um tipo enumerado para representar o estado do bloqueador de anúncios do usuário.
googlefc.AllowAdsStatusEnum !Object<string, number> Um tipo enumerado para representar o estado de permissão de anúncios do usuário.
googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum !Object<string, number> Um tipo enumerado para representar o status inicial de desativação do usuário nos estados dos EUA. Isso considera o estado dos EUA em que o usuário está localizado.
googlefc.GoogleFcConsentModeUserStatus !Object O tipo de retorno para googlefc.getGoogleConsentModeValues.
googlefc.ConsentModePurposeStatusEnum !Object<string, number> Um tipo enumerado para representar a decisão do usuário final para uma finalidade do modo de consentimento.
googlefc.usstatesoptout.overrideDnsLink undefined|boolean Um booleano que pode ser definido como verdadeiro para usar seu próprio link personalizado "Não vender nem compartilhar".
googlefc.ccpa.InitialCcpaStatusEnum

Legado. Preferir googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.
!Object<string, number> Um tipo enumerado para representar o status inicial das regulamentações estaduais dos EUA do usuário.
googlefc.ccpa.overrideDnsLink

Legado. Preferir googlefc.usstatesoptout.overrideDnsLink.
undefined|boolean Um booleano que pode ser definido como verdadeiro para usar seu próprio link personalizado "Não vender nem compartilhar".

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() número Retorna um valor no AdBlockerStatusEnum dependendo do status de bloqueio de anúncios do usuário.
googlefc.getAllowAdsStatus() número Retorna um valor no AllowAdsStatusEnum dependendo do status de permissão de anúncios do usuário.
googlefc.usstatesoptout.getInitialUsStatesOptOutStatus() número Retorna um valor no InitialUsStatesOptOutStatusEnum dependendo do status inicial de recusa do usuário em relação às regulamentações estaduais dos EUA. Isso considera a regulamentação que se aplica ao usuário com base na localização atual dele.
googlefc.usstatesoptout.openConfirmationDialog(function(boolean)) indefinido Abre a caixa de diálogo de confirmação de desativação das regulamentações estaduais dos EUA se o link padrão "Não vender nem compartilhar" for substituído.
googlefc.getGoogleConsentModeValues() !Object Retorna um objeto googlefc.GoogleFcConsentModeUserStatus que contém os valores atuais do modo de consentimento para o usuário, um para cada finalidade disponível.
googlefc.ccpa.getInitialCcpaStatus()

Legado. Prefira googlefc.usstatesoptout.getInitialUsStatesOptOutStatus().
número Retorna um valor no InitialCcpaStatusEnum dependendo do status inicial de recusa das regulamentações estaduais dos EUA do usuário.
googlefc.ccpa.openConfirmationDialog(function(boolean))

Legado. Prefira googlefc.usstatesoptout.openConfirmationDialog().
indefinido Abre a caixa de diálogo de confirmação de desativação das regulamentações estaduais dos EUA se o link padrão "Não vender nem compartilhar" for substituído.

Como testar e depurar no seu site

A ferramenta Privacidade e Mensagens oferece recursos de depuração e teste para você ver como mensagens específicas, subtipos de mensagens ou combinações de mensagens aparecem no seu site.

Pré-requisitos:

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

Para ver uma prévia em tempo real no seu site, use 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 recusa dos regulamentos estaduais dos EUA), gdpr (mensagens de consentimento do GDPR), monetization (mensagens do Offerwall), usfl (mensagens de recusa dos regulamentos estaduais dos EUA, específicas da Flórida), usnat (mensagens de recusa dos regulamentos estaduais dos EUA, todos os estados compatíveis, exceto a Flórida; equivalente a ccpa)

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

  • Teste as mensagens de recusa das regulamentações estaduais dos EUA — 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 ser mostradas ou não. Ele pode ser usado para controlar a renderização de mensagens em condições especificadas pelo editor, como status do 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 prossigam normalmente, enquanto chamar message.proceed(false) impede que as mensagens sejam mostradas na visualização de página.

Exemplo: suponha que você tenha este 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 assinantes.

<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 aos editores especificar que apenas tipos específicos de mensagens devem ser suprimidos. Use essa extensão de recurso para suprimir tipos de mensagens específicos sem suprimir outros tipos de mensagens.

As mensagens controladas específicas do tipo de mensagem são enviadas transmitindo um parâmetro adicional 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 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 de invocar qualquer função é adicionando-a ao callbackQueue.

Como diferentes tipos de dados ficam disponíveis em momentos distintos, uma função precisa ser adicionada como um mapa, com uma das seguintes strings como chave e a função a ser executada como 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 das estruturas de consentimento compatíveis são definidas e podem ser chamadas. A partir desse ponto, a execução de qualquer função com chave CONSENT_API_READY adicionada posteriormente é síncrona. Consulte as seções sobre frameworks do IAB para detalhes específicos de cada framework. Baixo
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 uma estrutura de consentimento compatível é conhecido (seja de uma execução anterior ou depois que o usuário interage com a mensagem de consentimento). A partir desse ponto, a execução de qualquer função com chave CONSENT_DATA_READY adicionada posteriormente é síncrona. Alta
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. Alta
CONSENT_MODE_DATA_READY As funções enviadas para a fila de callback com a chave CONSENT_MODE_DATA_READY são executadas quando os dados do [modo de consentimento](https://support.google.com/google-ads/answer/10000067) do Google (para uso com as tags do Google Ads e do Analytics) ficam disponíveis no fluxo. Quando os dados do modo de consentimento estiverem prontos, você poderá acessar os valores a qualquer momento usando googlefc.getGoogleConsentModeValues. Médio
INITIAL_US_STATES_OPT_OUT_DATA_READY As funções enviadas para a fila de callback com a chave INITIAL_US_STATES_OPT_OUT_DATA_READY são executadas quando os dados das regulamentações estaduais dos EUA ficam disponíveis no fluxo. Qualquer solicitação subsequente de dados de regulamentações estaduais dos EUA precisa ser feita chamando diretamente a API GPP (__gpp). Médio
INITIAL_CCPA_DATA_READY Chave legada para regulamentações estaduais dos EUA. Prefira INITIAL_US_STATES_OPT_OUT_DATA_READY.

As funções enviadas para a fila de callback com a chave INITIAL_CCPA_DATA_READY são executadas quando os dados das regulamentações estaduais dos EUA ficam disponíveis no fluxo. Qualquer solicitação subsequente de dados de regulamentações estaduais dos EUA precisa ser feita chamando diretamente a API GPP (__gpp).
Médio

googlefc.CallbackQueue {!Object}

Resumo do método:

Nome Tipo Parâmetro Tipo de retorno Papel
push(data) número data: um par de chave-valor em que a chave é um dos tipos de disponibilidade de dados e o valor é 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, INITIAL_US_STATES_OPT_OUT_DATA_READY, CONSENT_MODE_DATA_READY e (legado) 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.usstatesoptout = window.googlefc.usstatesoptout || {};
  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 para resposta a 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.usstatesoptout.InitialUsStatesOptOutStatusEnum{!Object<string, number>}

Representa os diferentes status de recusa do usuário em relação às regulamentações estaduais dos EUA. Os diferentes status são:

googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum = {
  // Something failed, status unknown.
  UNKNOWN: 0,
  // No US state regulation applies to this user.
  DOES_NOT_APPLY: 1,
  // A US state regulation applies to this user, and the user has not opted out yet.
  NOT_OPTED_OUT: 2,
  // A US state regulation applies to this user, and the user has opted out.
  OPTED_OUT: 3,
};

googlefc.GoogleFcConsentModeUserStatus{!Object}

O tipo do objeto retornado por googlefc.getGoogleConsentModeValues.

interface GoogleFcConsentModeUserStatus {

  // End user consent decision value for the ad_storage consent mode purpose.
  adStoragePurposeConsentStatus: number;

  // End user consent decision value for the ad_user_data consent mode purpose.
  adUserDataPurposeConsentStatus: number;

  // End user consent decision value for the ad_personalization consent mode purpose.
  adPersonalizationPurposeConsentStatus: number;

  // End user consent decision value for the analytics_storage consent mode purpose.
  analyticsStoragePurposeConsentStatus: number;
}

O valor de cada campo é um número que corresponde a um valor de tipo enumerado googlefc.ConsentModePurposeStatusEnum.


googlefc.ConsentModePurposeStatusEnum{!Object<string, number>}

Representa os diferentes valores possíveis de consentimento do usuário final para uma finalidade do modo de consentimento. Os valores diferentes são:

googlefc.ConsentModePurposeStatusEnum = {
  // Indicates either an error state, or that consent mode data is not ready
  // yet.
  UNKNOWN: 0,
  // Consent is granted for the given consent mode purpose.
  GRANTED: 1,
  // Consent is denied for the given consent mode purpose.
  DENIED: 2,
  // Consent is not applicable for the given consent mode purpose.
  NOT_APPLICABLE: 3,
  // The consent mode purpose has not been configured for use in the Privacy &
  // messaging UI.
  NOT_CONFIGURED: 4
};

googlefc.usstatesoptout.overrideDnsLink{undefined|boolean}

Defina esse campo como verdadeiro para ocultar o link padrão "Não vender nem compartilhar" e usar seu próprio link personalizado. Essa funcionalidade só é compatível com o Ad Manager.

Exemplo:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.usstatesoptout = window.googlefc.usstatesoptout || {};
  // Signals that the default DNS link will be overridden.
  googlefc.usstatesoptout.overrideDnsLink = true;
</script>

googlefc.ccpa.InitialCcpaStatusEnum{!Object<string, number>}

Representa os diferentes status de recusa do usuário em relação às regulamentações estaduais dos EUA. Os diferentes status são:

googlefc.ccpa.InitialCcpaStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  // No US state regulation applies to this user.
  CCPA_DOES_NOT_APPLY: 1,
  // A US state regulation applies to this user, and the user has not opted out yet.
  NOT_OPTED_OUT: 2,
  // A US state regulation 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 nem compartilhar" e usar seu próprio link personalizado. Se você definir esse campo como verdadeiro, será responsável por renderizar um link "Não vender nem compartilhar" no seu site. Esse campo precisa ser usado com openConfirmationDialog. Além disso, o uso do seu próprio link personalizado "Não vender nem compartilhar" para a funcionalidade de mensagens das "regulamentações estaduais dos EUA" só é compatível com o Ad Manager.

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 das regulamentações da UE, se houver, e mostra a mensagem das regulamentações da UE novamente para permitir que o usuário mude a decisão de consentimento.

Exemplo 1: exemplo simples de configuração de um link que mostra a mensagem de revogação quando clicado:

<a href="javascript:window.googlefc.showRevocationMessage();">Privacy and cookie settings</a>
<a href="javascript:window.googlefc.showRevocationMessage();" style="display: none;" id="revocation-link">Privacy and cookie settings</a>
<script>
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
  window.googlefc.callbackQueue.push({
    'CONSENT_API_READY':
    () => {
      // Update the revocation link so that it shows on the page.
      const revocationLink = document.getElementById('revocation-link');
      revocationLink.style.display = 'block';
    }
  });
</script>

Exemplo 2: se você quiser que o link fique visível apenas quando as regulamentações da UE se aplicarem ao usuário atual, use a fila de callback do googlefc com a API TCF para atualizar condicionalmente a exibição do botão com base no valor de gdprApplies depois de determinado. Para isso, use a chave de API CONSENT_API_READY.

<a href="javascript:window.googlefc.showRevocationMessage();" style="display: none;" id="revocation-link">Privacy and cookie settings</a>
<script>
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
  window.googlefc.callbackQueue.push({
    'CONSENT_API_READY':
    // Specifying "0" for the version parameter will result in the API call
    // using the latest version of the TCF spec.
    () => __tcfapi('addEventListener', 0, (tcdata, success) => {
      const revocationLink = document.getElementById('revocation-link');
      if (!success || !tcdata) {
        // Something went wrong, don't show the revocation link.
        revocationLink.style.display = 'none';
      }
      else if (tcdata.gdprApplies) {
        revocationLink.style.display = 'block';
      } else {
        // GDPR does not apply so don't show the revocation link.
        revocationLink.style.display = 'none';
      }
    })
  });
</script>

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.usstatesoptout = window.googlefc.usstatesoptout || {};
  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 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.usstatesoptout = window.googlefc.usstatesoptout || {};
  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.usstatesoptout.getInitialUsStatesOptOutStatus(): {number}

Retorna um valor em InitialUsStatesOptOutStatusEnum dependendo do status de desativação da regulamentação estadual dos EUA do usuário. A chave que precisa ser especificada para essa função é INITIAL_US_STATES_OPT_OUT_DATA_READY. Qualquer solicitação subsequente de dados de regulamentações estaduais dos EUA precisa ser feita chamando diretamente a API GPP (__gpp).

Se você estiver substituindo o link "Não vender nem compartilhar", use esse método para determinar quando incluir o link no seu site.

Exemplo:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.usstatesoptout = window.googlefc.usstatesoptout || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'INITIAL_US_STATES_OPT_OUT_DATA_READY':
    () => {
      switch (googlefc.usstatesoptout.getInitialUsStatesOptOutStatus()) {
        case googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.DOES_NOT_APPLY:
          // Insert handling for cases where no US state regulation applies to
          // the user.
          break;
        case googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.NOT_OPTED_OUT:
          // Insert handling for cases where a US state regulation applies to
          // the user, and the user has not opted out.
          break;
        case googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.OPTED_OUT:
          // Insert handling for cases where a US state regulation applies to the
          // user, and the user has opted out.
          break;
      }
    }
  });
</script>

googlefc.usstatesoptout.openConfirmationDialog(function(boolean)): {undefined}

Abre a caixa de diálogo de confirmação de desativação das regulamentações estaduais dos EUA se o link padrão "Não vender" for substituído. Depois que o usuário interage com a caixa de diálogo de confirmação, a função de callback fornecida é chamada com true se o usuário decidir desativar e false caso contrário.

Exemplo:

<script>
// This callback will be called with the user's US state regulation opt-out
// decision.
const usStateRegCompletionCallback = (userOptedOut) => {
  // Insert handling for user opt-out status here.
}
// Invoke the US state regulations confirmation dialog when the user clicks the
// link.
document.getElementById("your-custom-do-not-sell-link").addEventListener(
  "click", () => googlefc.usstatesoptout.openConfirmationDialog(usStateRegCompletionCallback));
</script>

googlefc.getGoogleConsentModeValues(): {!Object}

Retorna um objeto googlefc.GoogleFcConsentModeUserStatus que contém os valores atuais de cada finalidade do modo de consentimento, com base na decisão do usuário.

Consulte Como usar as soluções de gestão de consentimento do Google com suporte ao modo de consentimento para regulamentações da UE para saber mais sobre o uso pretendido.


googlefc.ccpa.getInitialCcpaStatus(): {number}

Retorna um valor no InitialCcpaStatusEnum dependendo do status de desativação da regulamentação estadual dos EUA do usuário. A chave que precisa ser especificada para essa função é INITIAL_CCPA_DATA_READY. Qualquer solicitação subsequente de dados de regulamentação estadual dos EUA precisa ser feita chamando diretamente a API GPP (__gpp).

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 no US state regulation applies to
          // the user.
          break;
        case googlefc.ccpa.InitialCcpaStatusEnum.NOT_OPTED_OUT:
          // Insert handling for cases where a US state regulation applies to
          // the user, and the user has not opted out.
          break;
        case googlefc.ccpa.InitialCcpaStatusEnum.OPTED_OUT:
          // Insert handling for cases where a US state regulation applies to the
          // user, and the user has opted out.
          break;
      }
    }
  });
</script>

googlefc.ccpa.openConfirmationDialog(function(boolean)): {undefined}

Abre a caixa de diálogo de confirmação de desativação das regulamentações estaduais dos EUA se o link padrão "Não vender" for substituído. Depois que o usuário interage com a caixa de diálogo de confirmação, a função de callback fornecida é chamada com true se o usuário decidir desativar, e false caso contrário.

Exemplo:

<script>
// This callback will be called with the user's US state regulation opt-out
// decision.
const usStateRegCompletionCallback = (userOptedOut) => {
  // Insert handling for user opt-out status here.
}
// Invoke the US state regulations 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 gestão de consentimento do Google para coletar consentimento do GDPR com o framework da TCF v2 do IAB, use a API da TCF v2 do IAB.

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

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 de fila de callback CONSENT_DATA_READY para garantir que os callbacks correspondentes sejam invocados apenas quando o consentimento do usuário for coletado e acessível usando a API TCF v2 do IAB. Isso pode ser usado em conjunto com o comando 'addEventListener'. Os dados fornecidos na primeira invocação do callback vão conter as seleções de consentimento do usuário (desde que a TCF v2 se aplique a ele). Com o lançamento da TCF v2.2, o comando 'getTCData' foi descontinuado.

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>

As soluções de gestão de consentimento do Google podem interpretar as opções de consentimento dos usuários para as regulamentações da UE no modo de consentimento do Google (saiba mais na Central de Ajuda).

O modo de consentimento pode ser implementado no modo básico ou no modo avançado, conforme descrito na documentação do Google Ads e do Analytics. Consulte seu departamento jurídico para saber qual modo de consentimento implementar para atender aos requisitos legais.

O modo de consentimento avançado é compatível por padrão. Depois de ativar o modo de consentimento na interface de Privacidade e Mensagens, não é necessário fazer mais nada.

Para implementar o modo de consentimento básico usando as soluções de gestão de consentimento do Google, use a chave de fila de callback CONSENT_MODE_DATA_READY para carregar condicionalmente suas tags do Google Ads e do Analytics quando os dados do modo de consentimento estiverem disponíveis. Os dados do modo de consentimento vão ficar disponíveis depois que o Funding Choices determinar que o modo de consentimento não se aplica a essa solicitação (por exemplo, porque as regulamentações da UE não se aplicam a essa solicitação) ou depois que um usuário tomar uma decisão de consentimento com base nas regulamentações da UE. Consulte seu departamento jurídico sobre os critérios a serem usados para determinar se as tags podem ser carregadas quando o modo de consentimento estiver disponível.

Por exemplo, para carregar suas tags quando os dados do modo de consentimento estiverem disponíveis, independentemente da decisão do usuário final:

<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

// Helper function to load Google Ads/Analytics tags once consent mode data is
// ready.
const loadGtagScript = () => {
  // Load gtag.js script - code taken from
  // https://developers.google.com/tag-platform/security/guides/consent?consentmode=basic#set_up_consent_mode
  var gtagScript = document.createElement('script');
  gtagScript.async = true;
  gtagScript.src = 'https://www.googletagmanager.com/gtag/js?id=<Google tag ID>';

  var firstScript = document.getElementsByTagName('script')[0];
  firstScript.parentNode.insertBefore(gtagScript,firstScript);
}

// Queue the callback using the CONSENT_MODE_DATA_READY key on the callbackQueue.
window.googlefc.callbackQueue.push({
  'CONSENT_MODE_DATA_READY':
  () => {
      loadGtagScript();
  },
});
</script>

Também é possível usar a API googlefc.getGoogleConsentModeValues() para receber os valores de finalidades individuais do modo de consentimento quando os dados desse modo estiverem disponíveis. Essa API retorna um objeto GoogleFcConsentModeUserStatus que contém um campo para cada finalidade do modo de consentimento compatível, e o valor de cada campo é um valor de tipo enumerado que indica o valor dessa finalidade do modo de consentimento.

Por exemplo, use googlefc.getGoogleConsentModeValues() para desbloquear as tags do Google Ads e do Analytics somente quando:

  • o usuário final toma uma decisão de consentimento com base nas regulamentações da UE que resulta na concessão de consentimento para todas as finalidades do modo de consentimento; ou
  • todas as finalidades do modo de consentimento não forem aplicáveis à solicitação atual (o que pode acontecer se as regulamentações da UE não se aplicarem ou se o modo de consentimento não estiver configurado para uma ou mais finalidades em Privacidade e Mensagens).
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

// Helper function to determine whether Google Ads and Analytics tags can be
// unblocked. Returns true if all consent mode purposes are set to GRANTED,
// NOT_APPLICABLE, or NOT_CONFIGURED.
const shouldUnblockConsentTags = (googleFcConsentModeStatus) => {
  const allConsentModeValues = [
    googleFcConsentModeStatus.adStoragePurposeConsentStatus,
    googleFcConsentModeStatus.adUserDataPurposeConsentStatus,
    googleFcConsentModeStatus.adPersonalizationPurposeConsentStatus,
    googleFcConsentModeStatus.analyticsStoragePurposeConsentStatus
  ];
  for (const consentModeValue of allConsentModeValues) {
    switch (consentModeValue) {
      case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_UNKNOWN:
        // Indicates either an error case or that consent mode data is not
        // ready yet. Cannot unblock tags until consent data is ready and valid,
        // so return false.
        return false;
      case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_GRANTED:
        // Consent is granted for this consent mode purpose.
        break;
      case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_DENIED:
        // Consent is denied for this consent mode purpose. Do not unblock tags.
        return false;
      case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_NOT_APPLICABLE:
        // Consent mode does not apply for this purpose.
        break;
      case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_NOT_CONFIGURED:
        // Consent mode not configured for this purpose.
        // If you configured support for Ads purposes but not Analytics purposes in the
        // Privacy & messaging UI, the value of `analyticsStoragePurposeConsentStatus` will
        // always be set to NOT_CONFIGURED. If you do not enable any Consent Mode support
        // in the Privacy & messaging UI, the values of all purposes will always be set to
        // NOT_CONFIGURED.
        break;
      default:
        console.log("Unexpected consent mode value encountered");
    }
  }
  // If all prior checks pass, all consent mode values are either GRANTED,
  // NOT_APPLICABLE, or NOT_CONFIGURED.
  return true;
};

// Helper function to load Google Ads/Analytics tags.
const loadGtagScript = () => {
  // Load gtag.js script - code taken from
  // https://developers.google.com/tag-platform/security/guides/consent?consentmode=basic#set_up_consent_mode
  var gtagScript = document.createElement('script');
  gtagScript.async = true;
  gtagScript.src = 'https://www.googletagmanager.com/gtag/js?id=<Google tag ID>';

  var firstScript = document.getElementsByTagName('script')[0];
  firstScript.parentNode.insertBefore(gtagScript,firstScript);
}

googlefc.callbackQueue.push({
  CONSENT_MODE_DATA_READY: () => {
    if (shouldUnblockConsentTags(googlefc.getGoogleConsentModeValues())) {
      loadGtagScript();
    }
  },
});
</script>

Se você usa as soluções de gestão de consentimento do Google para enviar mensagens de desativação das regulamentações estaduais dos EUA aos usuários finais de acordo com a estrutura GPP do IAB, use a API GPP do IAB.

Devido à natureza de recusa das regulamentações estaduais dos EUA, use 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.usstatesoptout = window.googlefc.usstatesoptout || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  window.googlefc.callbackQueue.push({
    'CONSENT_DATA_READY':
    () => __gpp('ping', (data, success) => {
        // Do something with consent data value.
    })
  });
</script>

Se você estiver usando as soluções de gestão de consentimento do Google para fornecer mensagens de desativação das regulamentações estaduais dos EUA aos usuários finais de acordo com a estrutura GPP do IAB, é possível fornecer seu próprio link personalizado "Não vender nem compartilhar" definindo a flag googlefc.usstatesoptout.overrideDnsLink como true.

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.usstatesoptout = window.googlefc.usstatesoptout || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Signals that the default DNS link will be overridden.
  window.googlefc.usstatesoptout.overrideDnsLink = true;

  // Register the callback for the initial US state regulations data.
  window.googlefc.callbackQueue.push({
      'INITIAL_US_STATES_OPT_OUT_DATA_READY': () => {
        if (googlefc.usstatesoptout.getInitialUsStatesOptOutStatus() ===
            googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.NOT_OPTED_OUT) {
          // TODO: Display custom Do Not Sell or Share link here.
        }
      }
    });
</script>

Isso garante que o link padrão "Não vender nem compartilhar" não seja renderizado. Em seguida, você precisa processar a interação do usuário com o link personalizado "Não vender nem compartilhar" invocando a caixa de diálogo de confirmação de desativação das regulamentações estaduais dos EUA.

Ao usar seu próprio link personalizado "Não vender nem compartilhar", você é responsável por garantir que ele esteja em conformidade com as regulamentações estaduais dos EUA. Além disso, o uso do seu próprio link personalizado "Não vender nem compartilhar" para a funcionalidade de mensagens das "regulamentações estaduais dos EUA" só é compatível com o Ad Manager.

<script>
// This callback will be called when the user makes a US state regulations
// decision.
const usStateRegCompletionCallback = (userOptedOut) => {
  if (userOptedOut) {
    // TODO: Hide custom Do Not Sell or Share link here.
  }
}
// Invoke the US state regulations opt-out confirmation dialog when the user
// clicks the link.
document.getElementById("your-custom-do-not-sell-link").addEventListener(
  "click", () => googlefc.usstatesoptout.openConfirmationDialog(usStateRegCompletionCallback));
</script>