Privacy & Messaging JavaScript API

简介

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

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

您还可以使用一些行业标准协议,通过这些工具征求用户意见:

在这些情况下,系统会使用这些 API 传达用户同意情况。

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

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

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.MessageTypeEnumArray。目前唯一支持的枚举是 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>

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

根据用户的 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 用户意见,则应使用 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_READYCONSENT_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>