隐私权和消息 JavaScript API

简介

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

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

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

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

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

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

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

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

字段摘要

名称 类型 定义
googlefc.controlledMessagingFunction function(!Object) 一个用于确定是否继续进行消息传递的函数。所有消息类型都支持此功能。
googlefc.callbackQueue !Array<!Object<字符串, 函数()>>|!Array&lt;function()&gt;|!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>}

  1. 现在，该方法在调用时始终返回空列表。

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>