隱私權與隱私權；訊息 JavaScript API

簡介

這個 API 提供工具，可與「隱私權與訊息」分頁提供的訊息互動。也可以執行下列操作：

• 限制特定使用者的訊息
• 查詢使用者的廣告封鎖狀態
• 算繪一個入口點，讓使用者撤銷歐盟法規同意聲明 (如適用)
• 覆寫美國州級法規的預設「不要銷售」連結
• 根據使用者在歐盟法規下的 Google 同意聲明模式狀態，有條件地載入 Google Ads 和 Analytics 代碼

等更多刊物。

您也可以使用下列工具，透過業界標準協定收集使用者同意聲明：

• 使用 IAB 資訊公開和同意聲明架構第 2.0 版規格的 GDPR 同意聲明
• 使用 IAB GPP 規格設定美國州級法規選擇退出

在這種情況下，系統會透過這些 API 傳達同意狀態。

您可以在網站上部署這項使用者訊息功能，方法如下：

1. 在多數情況下，您完全不需要重新加入代碼 - 只要使用者訊息在相關產品中發布，現有的 Google 發布商代碼或 AdSense 代碼就會部署使用者訊息。
2. 如果您使用廣告封鎖復原訊息，則必須明確在網頁中加入廣告封鎖標記。詳情請參閱 Ad Manager 和 AdSense 代碼標記操作說明。

googlefc 是使用者訊息功能在 JavaScript Window 上使用其 API 的全域命名空間。

注意： 這個參考資料使用 Google-Closure 類型註解。以下簡要說明幾個例子：

• boolean：JavaScript 布林型別。
• number|string：聯合類型。值為數字或字串。
• ?string：表示值為字串或空值。字串、數字和布林值的預設值不可為空值。
• Array<string>：字串陣列。
• googlefc.CallbackQueue：googlefc.CallbackQueue 類別的物件。
• !googlefc.CallbackQueue：表示值為 googlefc.CallbackQueue 型別，且非空值。根據預設，所有物件類型皆可為空值。
• !Array<!googlefc.CallbackQueue>：googlefc.CallbackQueue 物件的陣列。每個物件皆非空值。陣列本身並非空值。
• !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	!陣列<!物件<字串, 函式()>> | !陣列<函式()> | !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()	數字	根據使用者的廣告封鎖狀態，在 AdBlockerStatusEnum 中傳回值。
googlefc.getAllowAdsStatus()	號碼	根據使用者的廣告允許狀態，在 AllowAdsStatusEnum 中傳回值。
googlefc.usstatesoptout.getInitialUsStatesOptOutStatus()	數字	根據使用者最初的美國州級法規選擇拒絕狀態，在 InitialUsStatesOptOutStatusEnum 中傳回值。這項功能會根據使用者的目前所在位置，考量適用於使用者的法規。
googlefc.usstatesoptout.openConfirmationDialog(function(boolean))	未定義	如果預設的「不要銷售或分享」連結遭到覆寫，就會開啟美國州級法規選擇拒絕確認對話方塊。
googlefc.getGoogleConsentModeValues()	!Object	傳回 googlefc.GoogleFcConsentModeUserStatus 物件，其中包含使用者的目前同意聲明模式值，每個可用的同意聲明模式目的各有一項。
googlefc.ccpa.getInitialCcpaStatus() 舊版。建議使用 googlefc.usstatesoptout.getInitialUsStatesOptOutStatus()。	號碼	根據使用者最初的美國州級法規選擇拒絕狀態，在 InitialCcpaStatusEnum 中傳回值。
googlefc.ccpa.openConfirmationDialog(function(boolean)) 舊版。建議使用 googlefc.usstatesoptout.openConfirmationDialog()。	未定義	如果預設的「不要銷售或分享」連結遭到覆寫，就會開啟美國州級法規選擇拒絕確認對話方塊。

在網站上測試及偵錯

「隱私權與訊息」提供偵錯和測試功能，讓您查看特定訊息 (或訊息組合) 在實際網站上的顯示方式。

需求條件：

• 您要預覽的訊息必須發布在要測試的網站下方

您可以使用下列偵錯網址參數，在網站上查看即時預覽畫面：

偵錯參數	接受的值
fc	alwaysshow (觸發偵錯/預覽模式)
fctype	ab (廣告封鎖訊息)、ccpa (美國州級法規選擇退出訊息)、gdpr (GDPR 同意聲明訊息)、monetization (Offerwall 訊息)

以下列舉幾個範例，說明如何在網站 (foo.com) 上使用這項功能來預覽廣告：

• 測試美國州級法規選擇退出訊息 -- http://foo.com/?fc=alwaysshow&fctype=ccpa
• 測試 GDPR 訊息 -- http://foo.com/?fc=alwaysshow&fctype=gdpr

注意： 如果您預期會看到訊息，但未看到，或是訊息的行為不如預期，請嘗試清除 Cookie (或使用無痕模式) 來重設任何已儲存的狀態，然後再試一次。

欄位：說明和範例

googlefc.controlledMessagingFunction {function(!Object)}

這個函式會判斷是否應顯示訊息。可用於根據發布者指定的條件 (例如訂閱者狀態或網頁網址) 控管訊息的顯示方式。

如果您在其他指令碼載入前，在視窗上定義 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>

這項功能也有擴充功能，可讓發布商指定只抑制 Offerwall。使用這項功能擴充功能來禁止 Offerwall，而不禁止其他訊息類型。

重要事項： 目前這項功能擴充功能僅支援 Offerwall。

如要傳送 Offerwall 專屬的控管訊息，請將額外參數傳遞至 message.proceed()，也就是 googlefc.MessageTypeEnum 類型的 Array。

範例：以下範例使用 googlefc.controlledMessagingFunction 只抑制訂閱者的 Offerwall 放送，而不抑制其他訊息類型：

<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) 只會允許 Offerwall 顯示，但不保證 Offerwall 會確實顯示。Offerwall 支援許多自訂功能，這些功能可能會影響訊息的顯示時間，使用者應在使用 controlledMessagingFunction 時考量這項因素。舉例來說，您可以將訊息的頻率設定從「網頁瀏覽次數達 2 次」改為「網頁瀏覽次數為 0」來避免這項功能影響 Offerwall 的放送。

---

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 和 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，即可隱藏預設的「不要銷售或分享我的個人資訊」連結，並使用您自訂的「不要銷售或分享我的個人資訊」連結。

範例：

<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 搭配使用。

範例：

<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() 方法僅適用於使用簡易版 EU 同意聲明架構 (已於 10 月停用) 時

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.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 資訊公開和同意聲明架構第 2 版，以符合 GDPR 規定

如果您使用 Google 同意聲明管理解決方案，在 IAB 資訊公開和同意聲明架構第 2.0 版下收集 GDPR 同意聲明，則應使用 IAB 資訊公開和同意聲明架構第 2.0 版 API。

您可以使用 CONSENT_API_READY 回呼佇列索引鍵，確保只有在網頁上定義 IAB TCF 第 2 版 API 時，才會叫用對應的回呼。此參數應與 IAB TCF 第 2 版 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 第 2 版 API 收集並可存取使用者同意聲明時，才會叫用對應的回呼。這可與 'addEventListener' 指令搭配使用 - 您提供的回呼第一次呼叫時提供的資料，將包含使用者的同意選項 (只要資訊公開和同意聲明架構第 2.0 版適用於此使用者)。請注意，隨著 TCF 2.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 和 Analytics 說明文件，在基本模式或進階模式中導入同意聲明模式。您應諮詢法務部門，瞭解如何採用符合法律規定的同意聲明模式。

系統預設支援進階同意聲明模式；只要在隱私權與訊息工具 UI 中啟用同意聲明模式，就不需要進行其他操作。

如要使用 Google 同意聲明管理解決方案導入基本同意聲明模式，您可以使用 CONSENT_MODE_DATA_READY 回呼佇列鍵，在同意聲明模式資料可用時，有條件地載入 Google Ads 和 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 和 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 全球隱私權平台架構，遵守美國州級法規

如果您使用 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 全球隱私權平台架構下向使用者提供美國州別法規的選擇不採用訊息，可以將 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>

這可確保系統不會顯示預設的「不要銷售」或「分享」連結。接著，您需要呼叫美國州級法規選擇退出確認對話方塊，處理使用者與自訂「不要銷售或分享」連結的互動。

請注意，使用自訂的「不要銷售或分享」連結時，您有責任確保連結符合美國州級法規。

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