此页面由 Cloud Translation API 翻译。

隐私权和消息 JavaScript API

简介

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

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

您还可以使用以下工具通过某些业界标准协议征求用户意见：

依照 GDPR 征求用户意见（使用 IAB TCF v2 规范）
根据 IAB GPP CPRA 规范选择停用 CPRA

在这些情况下，用户意见状态会通过这些 API 传达。

您可以通过以下几种方式在您的网站上部署此用户消息功能：

在大多数情况下，您根本不需要重新添加代码，因为您现有的 Google 发布商代码或 AdSense 代码会在消息发布到相关产品中后部署用户消息。
如果您使用的是广告拦截收入挽回消息，则需要将广告拦截代码明确添加到您的网页中。如需了解详情，请参阅 Ad Manager 和 AdSense 代码添加说明。

googlefc 是用户消息功能在 JavaScript Window 上用于其 API 的全局命名空间。

注意：此引用使用了 google-closure 类型注解。以下是对示例的简要说明：

boolean：JavaScript 布尔值类型。
number|string：联合类型。值为数字或字符串。
?string：表示值是字符串类型或 null 值。默认情况下，字符串、数字和布尔值类型不可为 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<string, function()>> \| !Array<function()> \| !googlefc.CallbackQueue	对回调队列的引用队列，以异步执行用户消息查询查询。
`googlefc.CallbackQueue`	!Object	回调队列对象的类型。
`googlefc.AdBlockerStatusEnum`	!Object<string, number>	用于表示用户的广告拦截器状态的枚举。
`googlefc.AllowAdsStatusEnum`	!Object<string, number>	用于表示用户的 allow-ads 状态的枚举。
`googlefc.ccpa.InitialCcpaStatusEnum`	!Object<string, number>	用于表示用户初始 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

字段：说明和示例

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}

根据用户的 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>

如果您在 IAB TCF v2 框架下使用 Google 意见征求管理解决方案来依照 GDPR 征求 GDPR 意见，则应使用 IAB TCF v2 API。

您可以使用 CONSENT_API_READY 回调队列键来确保仅当网页上定义了 IAB TCF v2 API 时才会调用相应的回调。此政策应与 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 访问该 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 意见征求管理解决方案在 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 意见征求管理解决方案与适用于 CPRA 的 IAB GPP 框架结合使用，并在其中设置自定义“不出售”链接

如果您使用 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>