API Privacy & Messaging JavaScript

Introdução

Essa API fornece ferramentas para interagir com as mensagens oferecidas pela API guia "Mensagens". Ele serve para diversas coisas:

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

Você também pode usar essas ferramentas para solicitar o consentimento do usuário usando alguns padrões do setor protocolos:

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

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

  1. Na maioria dos casos, não é necessário reinserir as tags. Suas assinaturas do Google Editora Tag ou Implantações da tag do Google AdSense as mensagens aos usuários assim que elas forem publicadas no produto em questão.
  2. Se você estiver usando a mensagem de recuperação de bloqueio de anúncios, será necessário adicionar o anúncio a tag de bloqueio a sua página explicitamente. Consulte Anúncio Manager e Inclusão de tags no AdSense para mais informações.

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

Resumos de campo

Nome Tipo Definição
googlefc.controlledMessagingFunction function(!Object) Uma função que determina se é necessário continuar com alguma mensagem. Essa funcionalidade está disponível para todos os tipos de mensagens.
googlefc.callbackQueue !Array<!Object<string, function()>> | !Array&lt;function()&gt; | !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 allow-ads do usuário.
googlefc.ccpa.InitialCcpaStatusEnum !Object<string, number> Um enum para representar o status inicial da CPRA do usuário.
googlefc.ccpa.overrideDnsLink indefinido|booleano Um booleano que pode ser definido como "true" para usar um link "Não vender" personalizado.

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 objeto AllowAdsStatusEnum, dependendo do status de permissão de 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 "Não vender" padrão for substituído.

Como testar e depurar no seu site

Privacidade e de mensagens fornece recursos de depuração e teste que permitem ver qual é 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 você está comparando

É possível conferir uma visualização em tempo real no seu site usando o seguinte URL de depuração. parâmetros:

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 isso para visualização no seu site (foo.com):

  • Testar mensagens da CPRA: 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. Pode ser usada para bloquear 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 enquanto outros scripts estão sendo carregados, as mensagens não são exibidas até que você chame message.proceed(boolean). Chamar message.proceed(true) permite enviar mensagens para continue normalmente, enquanto chamar message.proceed(false) impede que qualquer mensagem sejam exibidos na visualização da página.

Exemplo: suponha que você tenha esse script na página que define uma função 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 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 aos editores parte do a versão Beta fechada do Offerwall para especificar que apenas ele deve ser suprimida. Outros tipos de mensagens não serão afetados quando esse recurso estiver em vigor.

Para conseguir mensagens controladas específicas do Offerwall, como message.proceed(), um Array do tipo googlefc.MessageTypeEnum.

Exemplo: este é um exemplo de como usar googlefc.controlledMessagingFunction para suprimir apenas a veiculação do Offerwall para os 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 global de callbacks para execução assíncrona de relacionadas a mensagens. A única maneira aceita de invocar uma função é adicionando-o ao callbackQueue.

Como diferentes tipos de dados ficam disponíveis em diferentes momentos, uma função deve ser adicionado como um mapa, com uma das seguintes strings como a chave e o função seja 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 callbacks com a chave CONSENT_API_READY são executadas quando as APIs das estruturas 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 será síncrona. Consulte as seções sobre frameworks do IAB (em inglês) para detalhes específicos sobre essa estrutura. 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 um framework compatível é conhecido, seja em uma execução anterior ou quando 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 será síncrona. Alta
AD_BLOCK_DATA_READY As funções enviadas para a fila de callbacks 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 será síncrona. Alta
INITIAL_CCPA_DATA_READY As funções enviadas para a fila de callbacks com INITIAL_CCPA_DATA_READY são executadas quando os dados da CPRA ficam disponíveis no fluxo. Qualquer solicitação subsequente de dados da CPRA precisa ser recebida chamando diretamente a API US Privacy (__uspapi). Médio

googlefc.CallbackQueue {!Object}

Resumo dos métodos:

Nome Tipo Parâmetro Tipo de retorno Papel
push(data) number data: um par de chave-valor com a chave como um dos dados. os tipos de disponibilidade 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. Número de comandos adicionados até o momento. Isso retorna o tamanho atual da matriz. Executa a função transmitida, na ordem em que os dados ficam disponíveis, então pela ordem em que essas funções são adicionadas ao 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. As 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. As 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 Não vender e usar um link personalizado Não vender.

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 a este usuário. A chave que deve ser especificada para esta 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 deve ser especificada para esta 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 objeto AllowAdsStatusEnum, dependendo do status de permissão dos anúncios do o usuário. A chave que deve ser especificada para esta 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 de o usuário. A chave que deve ser especificada para esta função é INITIAL_CCPA_DATA_READY: Qualquer solicitação posterior de dados da CPRA precisa podem ser obtidos 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 "Não vender" padrão for substituído. Quando o usuário interage com a caixa de diálogo de confirmação, o a função de callback será chamada com true se o usuário optar por não participar. Caso contrário, 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ê usa as soluções de gestão de consentimento do Google para receber consentimento do GDPR na estrutura TCF v2 do IAB, use o TCF v2 do IAB API.

Você pode usar o CONSENT_API_READY para garantir que os callbacks correspondentes sejam invocados somente quando a API TCF v2 do IAB é definida na página. Ela deve ser usada em conjunto com o '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>

Você pode usar o CONSENT_DATA_READY para garantir que os callbacks correspondentes sejam invocados. somente quando o consentimento do usuário é coletado e acessado usando a API TCF v2 do IAB. Ela pode ser usada em conjunto com o 'addEventListener' command - os dados fornecidos na primeira invocação do callback fornecido conterá as seleções de consentimento do usuário (desde que o TCF v2 se aplique a essa usuário). Com o lançamento do TCF v2.2, '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>

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

Se você usa as soluções de gestão de consentimento do Google para solicitar a recusa da CPRA de acordo com a estrutura GPP do IAB, use o GPP do IAB API.

Devido à natureza de recusa da regulamentação da CPRA, você pode usar o CONSENT_API_READY ou Chamada de retorno de CONSENT_DATA_READY chave de fila para garantir que a API GPP do IAB possa ser chamada e retorne dados de consentimento no momento em que os retornos de chamada são 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>

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

Se você usa as soluções de gestão de consentimento do Google para solicitar a recusa da CPRA de acordo com a estrutura GPP do IAB, é 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 padrão "Não vender" não seja renderizado. Observe que você são responsáveis por renderizar seu próprio link "Não vender" para estar em conformidade com a CPRA. Em seguida, você precisa lidar com a interação do usuário com um objeto Não Link de venda 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>