隐私权和消息 JavaScript API

简介

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

• 禁止向指定用户显示消息
• 查询用户的广告拦截器状态
• 呈现一个入口点，以便用户撤消对欧盟法规的同意
• 替换美国州级法规的默认“不出售”链接
• 根据用户的欧盟法规 Google 意见征求模式状态，有条件地加载 Google Ads 和 Google Analytics 代码

等等。

您还可以使用这些工具，通过业界标准协议征求用户同意：

• 使用 IAB TCF v2 规范征求 GDPR 意见征求
• 使用 IAB GPP 规范的美国州级法规选择退出

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

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

1. 在大多数情况下，您根本不需要重新添加代码，因为只要在相关产品中发布消息，您现有的 Google 发布商代码或 AdSense 代码就会部署用户消息。
2. 如果您使用的是广告拦截收入挽回消息，则需要将广告拦截代码明确添加到您的网页中。如需了解详情，请参阅 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.usstatesoptout.InitialUsStatesOptOutStatusEnum：InitialUsStatesOptOutStatusEnum 中包含的数字。
• !googlefc.ConsentModePurposeStatusEnum：ConsentModePurposeStatusEnum 中包含的数字。
• !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>	一个枚举，用于表示用户的“允许广告”状态。
googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum	!Object<string, number>	一个枚举，用于表示用户最初的美国州级法规选择退出状态。 这会考虑用户所在的美国州。
googlefc.GoogleFcConsentModeUserStatus	!Object	googlefc.getGoogleConsentModeValues 的返回值类型。
googlefc.ConsentModePurposeStatusEnum	!Object<string, number>	一个枚举，用于表示最终用户针对意见征求模式用途做出的决定。
googlefc.usstatesoptout.overrideDnsLink	undefined|boolean	一个布尔值，可设置为 true，以使用您自己的自定义“请勿出售或分享”链接。
googlefc.ccpa.InitialCcpaStatusEnum 旧版。首选 googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum。	!Object<string, number>	一个枚举，用于表示用户的初始美国州级法规状态。
googlefc.ccpa.overrideDnsLink 旧版。首选 googlefc.usstatesoptout.overrideDnsLink。	undefined|boolean	一个布尔值，可设置为 true，以使用您自己的自定义“请勿出售或分享”链接。

方法摘要

注意： 调用任何函数的唯一受支持方式是将其添加到 callbackQueue。

名称	返回值类型	定义
googlefc.showRevocationMessage()	未指定	清除意见征求记录并重新加载 googlefc 脚本，以显示适用于用户的意见征求消息。
googlefc.getAdBlockerStatus()	number	根据用户的广告拦截状态，返回 AdBlockerStatusEnum 中的值。
googlefc.getAllowAdsStatus()	number	根据用户的“允许广告”状态，返回 AllowAdsStatusEnum 中的值。
googlefc.usstatesoptout.getInitialUsStatesOptOutStatus()	数值	根据用户最初的美国州级法规选择退出状态，返回 InitialUsStatesOptOutStatusEnum 中的值。这会考虑根据用户当前所在位置适用于该用户的法规。
googlefc.usstatesoptout.openConfirmationDialog(function(boolean))	未指定	如果默认的“不出售/分享”链接被替换，则会打开美国州级法规选择退出确认对话框。
googlefc.getGoogleConsentModeValues()	!Object	返回一个 googlefc.GoogleFcConsentModeUserStatus 对象，其中包含用户的当前意见征求模式值，每个可用的意见征求模式用途对应一个值。
googlefc.ccpa.getInitialCcpaStatus() 旧版。首选 googlefc.usstatesoptout.getInitialUsStatesOptOutStatus()。	number	根据用户最初的美国州级法规选择退出状态，在 InitialCcpaStatusEnum 中返回一个值。
googlefc.ccpa.openConfirmationDialog(function(boolean)) 旧版。首选 googlefc.usstatesoptout.openConfirmationDialog()。	未指定	如果默认的“不出售/分享”链接被覆盖，则会打开美国州级法规选择退出确认对话框。

在网站上进行测试和调试

“隐私权和消息”工具提供调试和测试功能，让您可以在实际网站上查看特定消息、消息子类型或消息组合的效果。

前提条件：

• 您要预览的消息必须发布到您要测试的网站

您可以使用以下调试网址参数在网站上查看实时预览：

调试参数	允许使用的值
fc	alwaysshow（用于触发调试/预览模式）
fctype	ab（广告拦截消息）、ccpa（美国州级法规拒绝消息）、gdpr（GDPR 意见征求消息）、monetization（积分墙消息）、usfl（美国州级法规拒绝消息，佛罗里达州专用）、usnat（美国州级法规拒绝消息，所有受支持的州 [佛罗里达州除外]；等同于 ccpa）

以下是一些示例，展示了如何使用此功能在您的网站 (foo.com) 上进行预览：

• 测试美国州级法规选择退出消息 -- http://foo.com/?fc=alwaysshow&fctype=ccpa
• 测试 GDPR 消息 -- http://foo.com/?fc=alwaysshow&fctype=gdpr

注意：如果您希望看到某条消息，但没有看到，或者该消息的行为不符合预期，请尝试清除 Cookie（或使用无痕模式）来重置所有已保存的状态，然后重试。

字段：说明和示例

googlefc.controlledMessagingFunction {function(!Object)}

用于确定是否应显示消息的函数。它可用于根据发布商指定的条件（例如订阅者状态或网页网址）来控制消息呈现。

如果您在加载其他脚本之前在 Window 上定义 googlefc.controlledMessagingFunction，则在您调用 message.proceed(boolean) 之前，消息不会显示。调用 message.proceed(true) 可让消息照常显示，而调用 message.proceed(false) 则会阻止在网页浏览中显示任何消息。

注意 ：如果页面上定义了 googlefc.controlledMessagingFunction，则在调用 message.proceed() 之前，不会显示任何“隐私权和消息”消息。这可能会导致广告投放延迟。因此，您应确保在网页加载后不久调用 message.proceed()，以保证预期的消息和广告投放行为。

注意： 为保证功能正常，您必须在 Google Ads 脚本加载之前在窗口中定义该函数。

示例：假设您在网页上添加了以下脚本，该脚本定义了一个异步函数 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>

此功能还提供了一项扩展功能，允许发布商指定仅应禁止显示特定消息类型。使用此功能扩展程序可抑制特定消息类型，而不会抑制其他消息类型。

重要提示： 此功能扩展目前支持积分墙 (googlefc.MessageTypeEnum.OFFERWALL) 和广告拦截收入挽回消息 (googlefc.MessageTypeEnum.AD_BLOCKING)。

通过向 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>

提示： 调用 message.proceed(true) 只是允许积分墙显示，并不保证积分墙一定会显示。积分墙支持许多自定义设置，这些设置可能会影响消息的呈现时间，因此在使用 controlledMessagingFunction 时应考虑到这一点。例如，您可以考虑将消息的频次设置从“在网页浏览量达到 2 次后显示”更改为“在网页浏览量达到 0 次后显示”，以防止该功能影响积分墙的投放。

---

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 键控函数的执行都是同步的。	高
CONSENT_MODE_DATA_READY	当 Google [意见征求模式](https://support.google.com/google-ads/answer/10000067)数据（用于 Google Ads 和 Google Analytics 代码）在流程中可用时，系统会执行使用 CONSENT_MODE_DATA_READY 键推送到回调队列的函数。意见征求模式数据准备就绪后，您可以随时使用 googlefc.getGoogleConsentModeValues 访问意见征求模式值。	中
INITIAL_US_STATES_OPT_OUT_DATA_READY	当流程中提供美国州级法规数据时，系统会执行使用 INITIAL_US_STATES_OPT_OUT_DATA_READY 键推送到回调队列的函数。请注意，后续任何针对美国州级法规数据的请求都应通过直接调用 GPP API (__gpp) 来获取。	中
INITIAL_CCPA_DATA_READY	适用于美国州级法规的旧版键。首选 INITIAL_US_STATES_OPT_OUT_DATA_READY。 当流程中提供美国州级法规数据时，系统会执行使用 INITIAL_CCPA_DATA_READY 键推送到回调队列的函数。请注意，后续任何针对美国州级法规数据的请求都应通过直接调用 GPP API (__gpp) 来获取。	中

重要提示： CONSENT_API_READY 仅表示已定义支持的用户同意框架 API；用户同意字符串可能尚不可用。CONSENT_DATA_READY 键对应于可用的用户意见征求字符串，但 CONSENT_DATA_READY 键控函数在流程中的执行时间始终晚于 CONSENT_API_READY 键控函数。

注意： 为了向后兼容此 API 的旧版本，如果添加到队列中的元素是函数而不是映射，则该函数会在意见征求数据可用时执行（即，系统会将其视为使用 CONSENT_DATA_READY 键的函数）。如果在函数中请求广告拦截信息，则状态返回值为 UNKNOWN。

---

googlefc.CallbackQueue {!Object}

方法摘要：

名称	类型	参数	返回值类型	角色
push(data)	数值	data：一个键值对，其中键是数据可用性类型之一，值是要执行的 JavaScript 函数。 可接受的数据可用性键包括 CONSENT_API_READY、CONSENT_DATA_READY、AD_BLOCK_DATA_READY、INITIAL_US_STATES_OPT_OUT_DATA_READY、CONSENT_MODE_DATA_READY 和（旧版）INITIAL_CCPA_DATA_READY。	到目前为止添加的指令数量。此方法会返回数组的当前长度。	按照数据可用的顺序，然后按照这些函数添加到队列中的顺序，执行传入的函数。

示例：

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.usstatesoptout = window.googlefc.usstatesoptout || {};
  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.usstatesoptout.InitialUsStatesOptOutStatusEnum{!Object<string, number>}

表示用户对美国州级法规的不同选择退出状态。不同的状态包括：

googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum = {
  // Something failed, status unknown.
  UNKNOWN: 0,
  // No US state regulation applies to this user.
  DOES_NOT_APPLY: 1,
  // A US state regulation applies to this user, and the user has not opted out yet.
  NOT_OPTED_OUT: 2,
  // A US state regulation applies to this user, and the user has opted out.
  OPTED_OUT: 3,
};

---

googlefc.GoogleFcConsentModeUserStatus{!Object}

googlefc.getGoogleConsentModeValues 返回的对象类型。

interface GoogleFcConsentModeUserStatus {

  // End user consent decision value for the ad_storage consent mode purpose.
  adStoragePurposeConsentStatus: number;

  // End user consent decision value for the ad_user_data consent mode purpose.
  adUserDataPurposeConsentStatus: number;

  // End user consent decision value for the ad_personalization consent mode purpose.
  adPersonalizationPurposeConsentStatus: number;

  // End user consent decision value for the analytics_storage consent mode purpose.
  analyticsStoragePurposeConsentStatus: number;
}

每个字段的值都是一个数字，对应于 googlefc.ConsentModePurposeStatusEnum 枚举值。

---

googlefc.ConsentModePurposeStatusEnum{!Object<string, number>}

表示针对某种意见征求模式用途，最终用户可能给出的不同用户同意值。不同的值包括：

googlefc.ConsentModePurposeStatusEnum = {
  // Indicates either an error state, or that consent mode data is not ready
  // yet.
  UNKNOWN: 0,
  // Consent is granted for the given consent mode purpose.
  GRANTED: 1,
  // Consent is denied for the given consent mode purpose.
  DENIED: 2,
  // Consent is not applicable for the given consent mode purpose.
  NOT_APPLICABLE: 3,
  // The consent mode purpose has not been configured for use in the Privacy &
  // messaging UI.
  NOT_CONFIGURED: 4
};

---

googlefc.usstatesoptout.overrideDnsLink{undefined|boolean}

将此字段设为 true，即可隐藏默认的“不出售/分享”链接，并使用您自己的自定义“不出售/分享”链接。请注意，此功能仅在 Ad Manager 中受支持。

示例：

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.usstatesoptout = window.googlefc.usstatesoptout || {};
  // Signals that the default DNS link will be overridden.
  googlefc.usstatesoptout.overrideDnsLink = true;
</script>

---

googlefc.ccpa.InitialCcpaStatusEnum{!Object<string, number>}

注意： 在新代码中首选 googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum。

表示用户对美国州级法规的不同选择退出状态。不同的状态包括：

googlefc.ccpa.InitialCcpaStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  // No US state regulation applies to this user.
  CCPA_DOES_NOT_APPLY: 1,
  // A US state regulation applies to this user, and the user has not opted out yet.
  NOT_OPTED_OUT: 2,
  // A US state regulation applies to this user, and the user has opted out.
  OPTED_OUT: 3,
};

---

googlefc.ccpa.overrideDnsLink{undefined|boolean}

注意： 在新代码中，最好使用 googlefc.usstatesoptout.overrideDnsLink。

将此字段设为 true，即可隐藏默认的“不出售/分享”链接，并使用您自己的自定义“不出售/分享”链接。请注意，如果您将此字段设置为 true，则您需要负责在网站上呈现“请勿出售或分享”链接。此字段应与 openConfirmationDialog 结合使用。此外，只有 Ad Manager 支持使用您自己的自定义“不出售/分享”链接来实现“美国州级法规”消息功能。

示例：

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

注意： getConsentStatus() 方法仅适用于使用简化的欧盟用户意见征求框架的情况，该框架已于 2021 年 10 月弃用。如果调用此方法，它将始终返回 UNKNOWN（值 0）。

---

googlefc.getConsentedProviderIds(): {!Array<string>}

注意： getConsentedProviderIds() 方法仅适用于使用欧盟用户意见征求精简框架的情况，该框架已于 10 月弃用

1. 现在，调用此方法时始终会返回一个空列表。

---

googlefc.showRevocationMessage(): {undefined}

清除当前的欧盟法规意见征求记录（如果存在），并再次显示欧盟法规消息，以便用户更改其意见决定。

示例 1：设置一个链接，点击该链接后会显示撤消消息，这是一个简单的示例：

<a href="javascript:window.googlefc.showRevocationMessage();">Privacy and cookie settings</a>

提示： 如果在点击链接时 googlefc API 尚未加载到页面上，则该链接将不会生效。在实践中，googlefc API 通常会比大多数用户找到并点击此链接的速度更快地加载到网页上；不过，如果您只想在 googlefc 确定已加载到网页上时才显示该链接，则可以根据 CONSENT_API_READY API 密钥来显示该链接，如以下代码段所示。

<a href="javascript:window.googlefc.showRevocationMessage();" style="display: none;" id="revocation-link">Privacy and cookie settings</a>
<script>
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
  window.googlefc.callbackQueue.push({
    'CONSENT_API_READY':
    () => {
      // Update the revocation link so that it shows on the page.
      const revocationLink = document.getElementById('revocation-link');
      revocationLink.style.display = 'block';
    }
  });
</script>

示例 2：如果您只想在欧盟法规适用于当前用户时显示该链接，则可以将 googlefc 回调队列与 TCF API 结合使用，以便在确定 gdprApplies 值后，根据该值有条件地更新按钮的显示。为此，请使用 CONSENT_API_READY API 密钥。

<a href="javascript:window.googlefc.showRevocationMessage();" style="display: none;" id="revocation-link">Privacy and cookie settings</a>
<script>
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];
  window.googlefc.callbackQueue.push({
    'CONSENT_API_READY':
    // Specifying "0" for the version parameter will result in the API call
    // using the latest version of the TCF spec.
    () => __tcfapi('addEventListener', 0, (tcdata, success) => {
      const revocationLink = document.getElementById('revocation-link');
      if (!success || !tcdata) {
        // Something went wrong, don't show the revocation link.
        revocationLink.style.display = 'none';
      }
      else if (tcdata.gdprApplies) {
        revocationLink.style.display = 'block';
      } else {
        // GDPR does not apply so don't show the revocation link.
        revocationLink.style.display = 'none';
      }
    })
  });
</script>

---

googlefc.getAdBlockerStatus(): {number}

根据用户的广告拦截状态，返回 AdBlockerStatusEnum 中的值。应为此函数指定的键为 AD_BLOCK_DATA_READY。

示例：

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.usstatesoptout = window.googlefc.usstatesoptout || {};
  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.usstatesoptout = window.googlefc.usstatesoptout || {};
  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.usstatesoptout.getInitialUsStatesOptOutStatus(): {number}

根据用户的美国州级法规选择退出状态，返回 InitialUsStatesOptOutStatusEnum 中的值。应为此函数指定的键为 INITIAL_US_STATES_OPT_OUT_DATA_READY。请注意，后续任何针对美国州级法规数据的请求都应通过直接调用 GPP API (__gpp) 来获取。

如果您要替换“不出售或分享我的个人信息”链接，可以使用此方法来确定何时在网站上添加该链接。

示例：

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.usstatesoptout = window.googlefc.usstatesoptout || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'INITIAL_US_STATES_OPT_OUT_DATA_READY':
    () => {
      switch (googlefc.usstatesoptout.getInitialUsStatesOptOutStatus()) {
        case googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.DOES_NOT_APPLY:
          // Insert handling for cases where no US state regulation applies to
          // the user.
          break;
        case googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.NOT_OPTED_OUT:
          // Insert handling for cases where a US state regulation applies to
          // the user, and the user has not opted out.
          break;
        case googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.OPTED_OUT:
          // Insert handling for cases where a US state regulation applies to the
          // user, and the user has opted out.
          break;
      }
    }
  });
</script>

---

googlefc.usstatesoptout.openConfirmationDialog(function(boolean)): {undefined}

如果默认的“请勿出售”链接被覆盖，则会打开美国州级法规选择退出确认对话框。用户与确认对话框互动后，如果用户决定选择停用，则系统会使用 true 调用提供的回调函数，否则会使用 false 调用。

示例：

<script>
// This callback will be called with the user's US state regulation opt-out
// decision.
const usStateRegCompletionCallback = (userOptedOut) => {
  // Insert handling for user opt-out status here.
}
// Invoke the US state regulations confirmation dialog when the user clicks the
// link.
document.getElementById("your-custom-do-not-sell-link").addEventListener(
  "click", () => googlefc.usstatesoptout.openConfirmationDialog(usStateRegCompletionCallback));
</script>

---

googlefc.getGoogleConsentModeValues(): {!Object}

返回一个 googlefc.GoogleFcConsentModeUserStatus 对象，其中包含每种意见征求模式用途的当前值，具体取决于用户的意见征求决定。

如需了解预期用途，请参阅使用支持意见征求模式的 Google 意见征求管理解决方案，遵守欧盟法规。

---

googlefc.ccpa.getInitialCcpaStatus(): {number}

注意： 在新代码中首选 googlefc.usstatesoptout.getInitialUsStatesOptOutStatus()。

根据用户的美国州级法规选择退出状态，返回 InitialCcpaStatusEnum 中的值。应为此函数指定的键为 INITIAL_CCPA_DATA_READY。请注意，后续任何针对美国州级法规数据的请求都应通过直接调用 GPP API (__gpp) 来获取。

示例：

<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 no US state regulation applies to
          // the user.
          break;
        case googlefc.ccpa.InitialCcpaStatusEnum.NOT_OPTED_OUT:
          // Insert handling for cases where a US state regulation applies to
          // the user, and the user has not opted out.
          break;
        case googlefc.ccpa.InitialCcpaStatusEnum.OPTED_OUT:
          // Insert handling for cases where a US state regulation applies to the
          // user, and the user has opted out.
          break;
      }
    }
  });
</script>

---

googlefc.ccpa.openConfirmationDialog(function(boolean)): {undefined}

注意： 在新代码中，最好使用 googlefc.usstatesoptout.openConfirmationDialog。

如果默认的“请勿出售”链接被覆盖，则会打开美国州级法规选择退出确认对话框。用户与确认对话框互动后，如果用户决定停用，则系统会使用 true 调用提供的回调函数，否则会使用 false 调用。

示例：

<script>
// This callback will be called with the user's US state regulation opt-out
// decision.
const usStateRegCompletionCallback = (userOptedOut) => {
  // Insert handling for user opt-out status here.
}
// Invoke the US state regulations 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

如果您使用 Google 意见征求管理解决方案在 IAB TCF v2 框架下收集 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 访问时，才调用相应的回调。这可以与 '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 意见征求管理解决方案，以遵守欧盟法规

Google 意见征求管理解决方案可以解读用户针对Google 意见征求模式做出的欧盟法规意见征求选择（如需了解详情，请参阅帮助中心）。

如 Google Ads 和 Google Analytics 文档中所述，意见征求模式可以基本模式或高级模式实现。您应咨询法务部门，了解应实现哪种意见征求模式才能满足法律要求。

默认情况下，系统支持高级意见征求模式；在“隐私权和消息”界面中启用意见征求模式后，无需执行其他操作。

如需使用 Google 意见征求管理解决方案实现基本意见征求模式，您可以使用 CONSENT_MODE_DATA_READY 回调队列键，在意见征求模式数据可用后有条件地加载 Google Ads 和 Google Analytics 代码。在资助选项确定意见征求模式不适用于此请求（例如，因为欧盟法规不适用于此请求）后，或者在用户做出欧盟法规同意决定后，意见征求模式数据将可用。您应咨询法务部门，了解在意见征求模式可用后，应根据哪些标准来确定是否可以加载代码。

例如，无论最终用户的同意决定如何，只要意见征求模式数据可用，就加载代码：

<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

// Helper function to load Google Ads/Analytics tags once consent mode data is
// ready.
const loadGtagScript = () => {
  // Load gtag.js script - code taken from
  // https://developers.google.com/tag-platform/security/guides/consent?consentmode=basic#set_up_consent_mode
  var gtagScript = document.createElement('script');
  gtagScript.async = true;
  gtagScript.src = 'https://www.googletagmanager.com/gtag/js?id=<Google tag ID>';

  var firstScript = document.getElementsByTagName('script')[0];
  firstScript.parentNode.insertBefore(gtagScript,firstScript);
}

// Queue the callback using the CONSENT_MODE_DATA_READY key on the callbackQueue.
window.googlefc.callbackQueue.push({
  'CONSENT_MODE_DATA_READY':
  () => {
      loadGtagScript();
  },
});
</script>

您还可以使用 googlefc.getGoogleConsentModeValues() API 获取意见征求模式数据可用时各个意见征求模式用途的值。 此 API 会返回一个 GoogleFcConsentModeUserStatus 对象，其中包含每个受支持意见征求模式用途的一个字段，每个字段的值都是一个枚举值，用于指示该意见征求模式用途的值。

例如，您可以使用 googlefc.getGoogleConsentModeValues() 仅在以下任一情况下解除对 Google Ads 和 Google Analytics 代码的屏蔽：

• 最终用户做出依据欧盟法规的用户同意决定，从而同意所有意见征求模式用途，或者
• 所有意见征求模式用途均不适用于当前请求（如果欧盟法规不适用，或者未在“隐私权和消息”中为一个或多个用途配置意见征求模式，则可能会发生这种情况）。

<script>
// Make sure that the properties exist on the window.
window.googlefc = window.googlefc || {};
window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

// Helper function to determine whether Google Ads and Analytics tags can be
// unblocked. Returns true if all consent mode purposes are set to GRANTED,
// NOT_APPLICABLE, or NOT_CONFIGURED.
const shouldUnblockConsentTags = (googleFcConsentModeStatus) => {
  const allConsentModeValues = [
    googleFcConsentModeStatus.adStoragePurposeConsentStatus,
    googleFcConsentModeStatus.adUserDataPurposeConsentStatus,
    googleFcConsentModeStatus.adPersonalizationPurposeConsentStatus,
    googleFcConsentModeStatus.analyticsStoragePurposeConsentStatus
  ];
  for (const consentModeValue of allConsentModeValues) {
    switch (consentModeValue) {
      case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_UNKNOWN:
        // Indicates either an error case or that consent mode data is not
        // ready yet. Cannot unblock tags until consent data is ready and valid,
        // so return false.
        return false;
      case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_GRANTED:
        // Consent is granted for this consent mode purpose.
        break;
      case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_DENIED:
        // Consent is denied for this consent mode purpose. Do not unblock tags.
        return false;
      case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_NOT_APPLICABLE:
        // Consent mode does not apply for this purpose.
        break;
      case googlefc.ConsentModePurposeStatusEnum.CONSENT_MODE_PURPOSE_STATUS_NOT_CONFIGURED:
        // Consent mode not configured for this purpose.
        // If you configured support for Ads purposes but not Analytics purposes in the
        // Privacy & messaging UI, the value of `analyticsStoragePurposeConsentStatus` will
        // always be set to NOT_CONFIGURED. If you do not enable any Consent Mode support
        // in the Privacy & messaging UI, the values of all purposes will always be set to
        // NOT_CONFIGURED.
        break;
      default:
        console.log("Unexpected consent mode value encountered");
    }
  }
  // If all prior checks pass, all consent mode values are either GRANTED,
  // NOT_APPLICABLE, or NOT_CONFIGURED.
  return true;
};

// Helper function to load Google Ads/Analytics tags.
const loadGtagScript = () => {
  // Load gtag.js script - code taken from
  // https://developers.google.com/tag-platform/security/guides/consent?consentmode=basic#set_up_consent_mode
  var gtagScript = document.createElement('script');
  gtagScript.async = true;
  gtagScript.src = 'https://www.googletagmanager.com/gtag/js?id=<Google tag ID>';

  var firstScript = document.getElementsByTagName('script')[0];
  firstScript.parentNode.insertBefore(gtagScript,firstScript);
}

googlefc.callbackQueue.push({
  CONSENT_MODE_DATA_READY: () => {
    if (shouldUnblockConsentTags(googlefc.getGoogleConsentModeValues())) {
      loadGtagScript();
    }
  },
});
</script>

将 Google 意见征求管理解决方案与 IAB GPP 框架结合使用，以满足美国州级法规要求

如果您使用 Google 意见征求管理解决方案，在 IAB GPP 框架下向最终用户提供美国州级法规选择退出消息，则应使用 IAB GPP API。

由于美国州级法规采用的是“选择退出”机制，因此您可以使用 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.usstatesoptout = window.googlefc.usstatesoptout || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  window.googlefc.callbackQueue.push({
    'CONSENT_DATA_READY':
    () => __gpp('ping', (data, success) => {
        // Do something with consent data value.
    })
  });
</script>

将 Google 意见征求管理解决方案与 IAB GPP 框架结合使用，以遵守美国州级法规，并使用您自己的自定义“不出售/分享”链接

如果您使用 Google 意见征求管理解决方案，在 IAB GPP 框架下向最终用户提供美国州级法规“选择退出出售/分享个人信息”消息，则可以通过将 googlefc.usstatesoptout.overrideDnsLink 标志设置为 true 来提供您自己的自定义“请勿出售或分享我的个人信息”链接。

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.usstatesoptout = window.googlefc.usstatesoptout || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Signals that the default DNS link will be overridden.
  window.googlefc.usstatesoptout.overrideDnsLink = true;

  // Register the callback for the initial US state regulations data.
  window.googlefc.callbackQueue.push({
      'INITIAL_US_STATES_OPT_OUT_DATA_READY': () => {
        if (googlefc.usstatesoptout.getInitialUsStatesOptOutStatus() ===
            googlefc.usstatesoptout.InitialUsStatesOptOutStatusEnum.NOT_OPTED_OUT) {
          // TODO: Display custom Do Not Sell or Share link here.
        }
      }
    });
</script>

这样可以确保默认的“请勿出售或分享”链接不会呈现。然后，您需要通过调用美国州级法规选择退出确认对话框，来处理用户与自定义“不出售/分享”链接的互动。

请注意，如果您使用自己的自定义“不出售/分享”链接，则需要自行确保该链接符合美国州级法规。 此外，只有 Ad Manager 支持使用您自己的自定义“不出售/分享”链接来实现“美国州级法规”消息功能。

<script>
// This callback will be called when the user makes a US state regulations
// decision.
const usStateRegCompletionCallback = (userOptedOut) => {
  if (userOptedOut) {
    // TODO: Hide custom Do Not Sell or Share link here.
  }
}
// Invoke the US state regulations opt-out confirmation dialog when the user
// clicks the link.
document.getElementById("your-custom-do-not-sell-link").addEventListener(
  "click", () => googlefc.usstatesoptout.openConfirmationDialog(usStateRegCompletionCallback));
</script>