本頁面由 Cloud Translation API 翻譯而成。

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

簡介

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

禁止任何特定使用者收發訊息
查詢使用者的廣告封鎖狀態
允許使用者撤銷同意聲明 (如適用)

您也可以使用這些工具，透過某些業界標準通訊協定收集使用者同意聲明：

採用 IAB 資訊公開和同意聲明架構第 2 版規格的 GDPR 同意聲明
根據 IAB GPP CPRA 規格選擇停用 CPRA

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

您可以透過下列幾種方式在網站上部署這項使用者訊息功能：

在大部分情況下，您不需要重新標記。只要使用現有的 Google 發布商廣告代碼或 AdSense 廣告代碼，當訊息發布到相關產品後，系統就會部署使用者訊息。
如果您使用廣告封鎖復原訊息，則必須在網頁中明確加入廣告封鎖代碼。詳情請參閱 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.ccpa.InitialCcpaStatusEnum：InitialCcpaStatusEnum 中包含的數值。

詳情請參閱 Google 關閉說明文件。

欄位摘要

名稱	類型	定義
`googlefc.controlledMessagingFunction`	function(!Object)	判斷是否要繼續處理任何訊息的函式。這項功能適用於所有訊息類型。
`googlefc.callbackQueue`	!Array<!Object<string, function()>> \| !Array<function()> \| !googlefc.CallbackQueue	使用者訊息傳遞查詢的回呼佇列參考資料。
`googlefc.CallbackQueue`	!物件	回呼佇列物件的類型。
`googlefc.AdBlockerStatusEnum`	!Object<string, number>	代表使用者廣告攔截器狀態的列舉。
`googlefc.AllowAdsStatusEnum`	!Object<string, number>	代表使用者的允許廣告狀態列舉項目。
`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` (Offerwall 訊息)

以下舉例說明如何在您的網站 (foo.com) 上預覽：

測試 CPRA 訊息 -- http://foo.com/?fc=alwaysshow&fctype=ccpa
測試 GDPR 訊息 -- http://foo.com/?fc=alwaysshow&fctype=gdpr

欄位：說明和範例

googlefc.controlledMessagingFunction {function(!Object)}

決定是否應顯示訊息的函式。可用來在發布者指定的條件 (例如訂閱者狀態或網頁網址) 上限制訊息算繪作業。

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

我們還提供了這項功能，讓參與 Offerwall 封閉 Beta 版的發布商指定只應封鎖 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>

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>

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

您可以使用 CONSENT_API_READY 回呼佇列金鑰，確保只有在網頁定義 IAB 資訊公開和同意聲明架構第 2 版 API 時，才會叫用對應的回呼。這應搭配 IAB 資訊公開和同意聲明架構第 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 資訊公開和同意聲明架構第 2 版 API 存取使用者同意時，才會叫用對應的回呼。這可與 'addEventListener' 指令搭配使用；首次叫用所提供回呼時提供的資料，就會包含使用者選擇的同意聲明選項 (只要資訊公開和同意聲明架構第 2 版適用於這位使用者)。請注意，隨著資訊公開和同意聲明架構第 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 同意聲明管理解決方案，搭配 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>

搭配自訂的「不要銷售」連結，搭配 CPRA 適用的 IAB GPP 架構使用 Google 同意聲明管理解決方案

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