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:
- consentimento do GDPR usando a especificação do TCF v2.0 do IAB
- Desativação da CPRA usando a especificação da CPRA do GPP do IAB (em inglês)
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:
- 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.
- 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<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 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>
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>}
- 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>
Como usar as soluções de gestão de consentimento do Google com o TCF v2 do IAB para o GDPR
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>