此页面由 Cloud Translation API 翻译。

隐私权和消息 JavaScript API

简介

此 API 提供了一些工具，用于与隐私权和 “消息”标签页借助该控制台，您可以执行以下操作：

禁止任何指定用户发送消息
查询用户的广告屏蔽状态
允许用户撤消同意（如果适用）

您还可以使用这些工具，依照某些业界标准征求用户意见协议：

依照 IAB TCF v2 规范就 GDPR 征求用户意见
根据 IAB GPP CPRA 规范停用 CPRA

在这些情况下，用户同意情况会通过相应 API 传达。

只需几个简单的步骤，方式：

在大多数情况下，您根本不需要重新标记 - 您的现有 Google 出版商代码或 AdSense 代码部署并在相关产品中发布后向用户显示消息。
如果您使用了广告拦截收入挽回消息，则需要将来明确屏蔽此类屏蔽标记请参阅广告经理和 AdSense 代码植入说明。

googlefc 是用户消息传递功能使用的全局命名空间。Window

</ph> 注意：此参考文档使用了 google-closure 类型注释。以下是简要介绍举例说明： <ph type="x-smartling-placeholder">

boolean：JavaScript 布尔值类型。
number|string：联合类型。值为任意数字或字符串。
?string：表示值是字符串类型或 null。以下各项不能为字符串、数字和布尔值类型为空默认值。
Array<string>：字符串数组。
googlefc.CallbackQueue：googlefc.CallbackQueue 类的对象。
!googlefc.CallbackQueue：表示某个值为 googlefc.CallbackQueue 的类型，而不是 null。默认情况下，所有对象类型都可以为 null。
!Array<!googlefc.CallbackQueue>：googlefc.CallbackQueue 对象的数组。每个对象都不为 null。数组本身不为 null。
!googlefc.ConsentStatusEnum：ConsentStatusEnum 中包含的数字。
!googlefc.AdBlockerStatusEnum：AdBlockerStatusEnum 中包含的数字。
!googlefc.AllowAdsStatusEnum：AllowAdsStatusEnum 中包含的数字。
!googlefc.ccpa.InitialCcpaStatusEnum：InitialCcpaStatusEnum 中包含的数字。

。如需了解更多详情，请参阅 Google Closure 文档。

字段摘要

名称	类型	定义
`googlefc.controlledMessagingFunction`	function(!Object)	一个用于确定是否继续进行消息传递的函数。所有消息类型都支持此功能。
`googlefc.callbackQueue`	!Array<!Object<字符串, 函数()>>\|!Array<function()>\|!googlefc.CallbackQueue	引用回调队列，以异步执行用户消息查询。
`googlefc.CallbackQueue`	!Object	回调队列对象的类型。
`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()`	号码	根据用户的初始 CPRA 状态，在 `InitialCcpaStatusEnum` 中返回一个值。
`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

。 <ph type="x-smartling-placeholder">

字段：说明和示例

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）。

示例：这是一个使用 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>

googlefc.callbackQueue {!Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue}

引用全局回调队列，以异步执行与短信相关的通话。调用任何函数的唯一支持方法是添加到 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}

返回 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 意见征求管理解决方案来收集 GDPR 用户意见则应该使用 IAB TCF v2 API。

您可以使用 CONSENT_API_READY 回调队列键，以确保仅在网页上定义了 IAB TCF v2 API。这应该与替换为 'addEventListener' 命令。

示例：

<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>

您可以使用 CONSENT_DATA_READY 回调队列键，以确保调用相应的回调仅在已征得用户同意且可以使用 IAB TCF v2 API 访问的情况下才显示。这可与 'addEventListener' 命令 - 首次调用所提供的回调时提供的数据将包含用户的意见征求选项（只要 TCF v2 适用于此用户）。请注意，TCF v2.2 发布后， '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('addEventListener', 2.2, (data, success) => {
      // Do something with consent data value; this callback may be invoked
      // multiple times if user consent selections change.
    })
  });
</script>

结合使用 Google 意见征求管理解决方案和适用于 CPRA 的 IAB GPP 框架

如果您使用 Google 意见征求管理解决方案收集 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 意见征求管理解决方案和适用于 CPRA 的 IAB GPP 框架，并附带自定义的“不出售”链接

如果您使用 Google 意见征求管理解决方案收集 CPRA 拒绝联系名单在 IAB GPP 框架下，可以提供自定义的“不销售”链接将 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>

这样可确保默认的“不出售”链接不会呈现。请注意，负责呈现您自己的“不出售”链接，以符合规定。然后，您需要自行处理用户与自定义“Do Not” 通过调用 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>