简介
此 API 提供了与“隐私权和消息”标签页提供的消息进行交互的工具。借助该控制台,您可以执行以下操作:
- 禁止任何指定用户收发消息
- 查询用户的广告屏蔽状态
- 允许用户撤消同意(如果适用)
您还可以使用一些行业标准协议,通过这些工具征求用户意见:
- 依照 IAB TCF v2 规范征求 GDPR 的意见
- 通过 IAB GPP CPRA 规范选择退出 CPRA
在这些情况下,系统会使用这些 API 传达用户同意情况。
您可以通过以下几种方式在您的网站上部署此用户消息功能:
- 在大多数情况下,您不需要重新添加代码,因为一旦消息在相关产品中发布,您现有的 Google 发布商代码或 AdSense 代码就会部署用户消息。
- 如果您使用了广告拦截收入挽回消息,则需要将广告拦截代码明确添加到您的网页中。如需了解详情,请参阅 Ad Manager 和 AdSense 代码添加说明。
googlefc
是全局消息传递命名空间,用户消息传递功能可将其用于 JavaScript 上的 API。Window
字段摘要
名称 | 类型 | 定义 |
---|---|---|
googlefc.controlledMessagingFunction
|
函数(!Object) | 用于确定是否继续进行任何消息的函数。所有消息类型都支持此功能。 |
googlefc.callbackQueue
|
!Array<!Object<string, 函数()>> | !Array<函数()> | !googlefc.CallbackQueue | 引用用户队列中查询异步执行的回调队列。 |
googlefc.CallbackQueue
|
!对象 | 回调队列对象的类型。 |
googlefc.AdBlockerStatusEnum
|
!Object<字符串, 数字> | 表示用户的广告拦截器状态的枚举。 |
googlefc.AllowAdsStatusEnum
|
!Object<字符串, 数字> | 用于表示用户的“允许-广告”状态的枚举。 |
googlefc.ccpa.InitialCcpaStatusEnum
|
!Object<字符串, 数字> | 表示用户初始 CPRA 状态的枚举。 |
googlefc.ccpa.overrideDnsLink
|
未定义|布尔值 | 一个布尔值,可设置为 true 以使用自定义“不出售”链接。 |
方法摘要
名称 | 返回类型 | 定义 |
---|---|---|
googlefc.showRevocationMessage()
|
未定义 |
清除用户意见征求记录,并重新加载 googlefc 脚本,以显示适用于用户的用户意见征求消息。
|
googlefc.getAdBlockerStatus()
|
数值 |
返回 AdBlockerStatusEnum 中的值,具体取决于用户的广告屏蔽状态。
|
googlefc.getAllowAdsStatus()
|
数值 |
返回 AllowAdsStatusEnum 中的值,具体取决于用户的“允许展示广告”状态。
|
googlefc.ccpa.getInitialCcpaStatus()
|
数值 |
返回 InitialCcpaStatusEnum 中的值,具体取决于用户的初始 CPRA 状态。
|
googlefc.ccpa.openConfirmationDialog(function(boolean))
|
未定义 | 如果默认的“不出售”链接已被覆盖,系统会打开 CPRA 确认对话框。 |
在网站上进行测试和调试
“隐私权和消息”页面提供了调试和测试功能,可让您查看特定消息(或消息组合)在实际网站上的显示效果。
前提条件:
- 您要预览的消息必须发布在接受测试的网站下
您可以使用以下调试网址参数在您的网站上查看实时预览:
调试参数 | 允许使用的值 |
---|---|
fc |
alwaysshow (用于触发调试/预览模式) |
fctype |
ab (广告拦截消息)、ccpa (CPRA 拒绝消息)、gdpr (GDPR 用户意见征求消息)、monetization (积分墙消息) |
下面列举了一些示例来介绍如何使用此文件在网站上预览 (foo.com):
- 测试 CPRA 消息 --
http://foo.com?fc=alwaysshow&fctype=ccpa
- 测试 GDPR 消息 --
http://foo.com?fc=alwaysshow&fctype=gdpr
字段:说明和示例
googlefc.controlledMessagingFunction {function(!Object)}
用于确定是否应显示消息的函数。它可用于控制在发布商指定的条件(例如订阅者状态或网页网址)上呈现消息。
当您在其他脚本加载之前在 Window 上定义 googlefc.controlledMessagingFunction
时,消息才会显示,直到您调用 message.proceed(boolean)
为止。调用 message.proceed(true)
可以照常进行消息传递,而调用 message.proceed(false)
可以阻止针对网页浏览显示任何消息。
示例:假设您在页面上添加了以下脚本,该脚本定义了一个异步函数 determineIfUserIsSubscriber()
,用于检查已登录用户是否为订阅者。
<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>
此示例展示了如何使用 googlefc.controlledMessagingFunction
仅向非订阅者显示消息。
<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>
积分墙封闭式 Beta 版的发布商可以通过向 message.proceed()
提供附加参数来指定应仅限制积分墙。此参数是类型为 googlefc.MessageTypeEnum
的 Array
。目前唯一支持的枚举是 OFFERWALL
,但未来可能会添加其他消息类型。
示例:假设您拥有与上面相同的 determineIfUserIsSubscriber()
函数。以下是使用 googlefc.controlledMessagingFunction
仅禁止订阅者订阅 积分墙而不抑制其他消息类型的示例:
<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>
对消息传递相关调用的异步执行全局回调队列的引用。调用任何函数的唯一支持方法是将其添加到 callbackQueue
。
由于不同类型的数据在不同的时间可用,因此应将函数作为映射添加,其中以下字符串之一是键,要执行的函数是值。
支持的键:
密钥名称 | 用法 | 相对延迟时间 |
---|---|---|
CONSENT_API_READY
|
定义支持调用的意见征求框架的 API 后,系统会通过 CONSENT_API_READY 键推送到回调队列的函数。从此之后,任何后续添加 CONSENT_API_READY 键控函数的函数都是同步的。有关框架专用的详细信息,请参阅下文有关 IAB 框架的部分。
|
低 |
CONSENT_DATA_READY
|
已知在受支持的用户意见征求框架下征求用户意见后(通过之前的执行方式或用户与用户意见征求消息互动时),系统会使用 CONSENT_DATA_READY 键推送到回调队列的函数。从此时开始,任何后续添加 CONSENT_DATA_READY 键控函数的函数都是同步执行的。 |
高 |
AD_BLOCK_DATA_READY
|
当数据流中包含广告拦截数据时,系统会执行通过 AD_BLOCK_DATA_READY 键推送到回调队列的函数。从此之后,任何后续添加 AD_BLOCK_DATA_READY 键控函数的函数都是同步的。 |
高 |
INITIAL_CCPA_DATA_READY
|
当 CPRA 数据在数据流中提供时,系统会执行推送到 INITIAL_CCPA_DATA_READY 的回调队列的函数。请注意,任何后续 CPRA 数据请求都应直接调用 US Privacy API (__uspapi ) 来完成。
|
中 |
googlefc.CallbackQueue {!Object}
方法摘要:
名称 | 类型 | 参数 | 返回类型 | 角色 |
---|---|---|---|---|
push(data)
|
数值 |
data :键值对,键作为数据可用性类型之一,值为要执行的 JavaScript 函数。可接受的数据可用性键包括 CONSENT_API_READY 、CONSENT_DATA_READY 、AD_BLOCK_DATA_READY 和 INITIAL_CCPA_DATA_READY 。
|
到目前为止添加的命令数量。这会返回数组的当前长度。 | 按照数据可用的顺序执行这些函数,然后按照这些函数添加到队列中的顺序执行。 |
例如:
<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>}
表示用户的不同广告屏蔽状态。不同的状态如下:
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>}
表示用户的不同广告屏蔽允许状态。不同的状态如下:
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>}
表示用户的不同广告屏蔽允许状态。不同的状态如下:
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}
将此字段设为 true 可隐藏默认的“不出售”链接,并使用自定义“不出售”链接。
例如:
<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>
方法:说明和示例
googlefc.getConsentStatus(): {number}
googlefc.getConsentedProviderIds(): {!Array<string>}
- 现在,调用时一律会返回空列表。
googlefc.showRevocationMessage(): {undefined}
清除当前的意见征求记录,并显示适用于此用户的意见征求消息。应为此函数指定的键为 CONSENT_DATA_READY
。
例如:
<button type="button" onclick="googlefc.callbackQueue.push({'CONSENT_DATA_READY': () => googlefc.showRevocationMessage()});">
Click here to revoke
</button>
googlefc.getAdBlockerStatus(): {number}
根据用户的广告拦截状态,返回 AdBlockerStatusEnum 中的值。应为此函数指定的键为 AD_BLOCK_DATA_READY
。
例如:
<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}
返回 AllowAdsStatusEnum
中的值,具体取决于用户的“允许展示广告”状态。应为此函数指定的键为 AD_BLOCK_DATA_READY
。
例如:
<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}
根据用户的 CPRA 状态,返回 InitialCcpaStatusEnum
中的值。应为此函数指定的键为 INITIAL_CCPA_DATA_READY
。请注意,任何后续 CPRA 数据请求都应直接调用 US Privacy API (__uspapi
) 来完成。
例如:
<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}
如果默认的“不出售”链接已被覆盖,则打开 CPRA 确认对话框。在用户与确认对话框互动后,如果用户决定退出,系统将使用 true
调用所提供的回调函数,否则调用 false
。
例如:
<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>
将 Google 意见征求管理解决方案与 IAB TCF v2 搭配使用,以遵守 GDPR
如果您根据 IAB TCF v2 框架使用 Google 意见征求管理解决方案来收集 GDPR 用户意见,则应使用 IAB TCF v2 API。
您可以使用 CONSENT_API_READY
回调队列键,以确保仅当网页上定义了 IAB TCF v2 API 时,才会调用相应的回调。此方法应与 IAB TCF v2 API 的 'addEventListener'
命令结合使用,因为使用同步 'getTCData'
命令提取的用户意见可能尚不可用。
例如:
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
// Queue the callback using the CONSENT_API_READY key on the callbackQueue.
window.googlefc.callbackQueue.push({
'CONSENT_API_READY':
() => __tcfapi('addEventListener', 2.0, (data, success) => {
// Do something with consent data value; this callback may be invoked
// multiple times as user completes consent flow.
})
});
</script>
您可以使用 CONSENT_DATA_READY
回调队列键,以确保仅在使用 IAB TCF v2 API 收集和访问用户意见时调用相应的回调。此参数可以与 'getTCData'
命令结合使用,因为您可以使用同步方法提取用户的同意情况。
例如:
<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
// Queue the callback using the CONSENT_DATA_READY key on the callbackQueue.
window.googlefc.callbackQueue.push({
'CONSENT_DATA_READY':
() => __tcfapi('getTCData', 2.0, (data, success) => {
// Do something with consent data value.
})
});
</script>
将 Google 意见征求管理解决方案与 IAB GPP 框架(适用于 CPRA)搭配使用
如果您使用 Google 意见征求管理解决方案来根据 IAB GPP 框架停用 CPRA,则应使用 IAB GPP API。
由于 CPRA 法规的停用性质,您可以使用 CONSENT_API_READY
或 CONSENT_DATA_READY
回调队列键来确保 IAB GPP API 是可调用的,并在调用回调时返回用户意见征求数据。
<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>
将 Google 意见征求管理解决方案与 IAB GPP 框架搭配使用,以实施包含自定义“不出售”链接的 CPRA
如果您使用 Google 意见征求管理解决方案来根据 IAB GPP 框架收集停用 CPRA,则可以通过将 googlefc.ccpa.overrideDnsLink
标志设置为 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>
这样可确保默认的“不出售”链接不会呈现。请注意,您有责任呈现自己的“不出售”链接,以确保符合 CPRA 要求。然后,您需要通过调用 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>