本頁面由 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 Closure 文件。

原野摘要

名稱	類型	定義
`googlefc.controlledMessagingFunction`	函式(!Object)	決定是否繼續繼續接收任何訊息的函式。所有訊息類型都支援這項功能。
`googlefc.callbackQueue`	!Array<!Object<string, function()>> \| !Array<function()> \| !googlefc.CallbackQueue	用於非同步執行使用者訊息查詢的回呼佇列。
`googlefc.CallbackQueue`	!Object	回呼佇列物件的類型。
`googlefc.AdBlockerStatusEnum`	!Object<字串, number>	代表使用者廣告攔截器狀態的列舉。
`googlefc.AllowAdsStatusEnum`	!Object<字串, number>	一個列舉列舉使用者的允許廣告狀態。
`googlefc.ccpa.InitialCcpaStatusEnum`	!Object<字串, number>	代表使用者初始 CPRA 狀態的列舉。
`googlefc.ccpa.overrideDnsLink`	未定義\|布林值	布林值，可設為使用自訂自訂「不要販售」連結。

方法摘要

名稱	傳回類型	定義
`googlefc.showRevocationMessage()`	未定義	清除同意聲明記錄並重新載入 `googlefc` 指令碼，以顯示適用的使用者同意授權訊息。
`googlefc.getAdBlockerStatus()`	數字	根據使用者的廣告封鎖狀態，傳回 `AdBlockerStatusEnum` 中的值。
`googlefc.getAllowAdsStatus()`	數字	根據使用者的允許廣告狀態，傳回 `AllowAdsStatusEnum` 中的值。
`googlefc.ccpa.getInitialCcpaStatus()`	數字	根據使用者的初始 CPRA 狀態，傳回 `InitialCcpaStatusEnum` 中的值。
`googlefc.ccpa.openConfirmationDialog(function(boolean))`	未定義	如果覆寫預設的「不要販售」連結，系統會開啟 CPRA 確認對話方塊。

在網站上測試及偵錯

「隱私權與訊息」提供偵錯和測試功能，方便您查看實際訊息 (或訊息組合) 的實際樣貌。

需求條件：

您要預覽的訊息必須發布到要測試的網站底下

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

偵錯參數	接受的值
`fc`	`alwaysshow` (用於觸發偵錯/預覽模式)
`fctype`	`ab` (廣告封鎖訊息)、`ccpa` (CPRA 選擇退出訊息)、`gdpr` (GDPR 同意授權訊息)、`monetization` (優惠牆訊息)

以下示範如何使用在網站 (foo.com) 上預覽預覽畫面：

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

欄位：說明和範例

googlefc.controlledMessagingFunction {function(!Object)}

用於決定是否要顯示訊息的函式。這項功能可用來限制在發布商指定的條件 (例如訂閱者狀態或網頁網址) 中轉譯訊息。

如果在載入其他指令碼之前在 Window 中定義 googlefc.controlledMessagingFunction，則必須先呼叫 message.proceed(boolean)，才會顯示訊息。呼叫 message.proceed(true) 可照常照常傳送訊息，而呼叫 message.proceed(false) 則就不會針對網頁瀏覽顯示任何訊息。

範例：假設您在網頁中有這個指令碼，定義了非同步函式 determineIfUserIsSubscriber()，用於檢查已登入的使用者是否為訂閱者。

<head>
  <script>
    window.isSubscriber = undefined;
    function determineIfUserIsSubscriber() {
      if (isSubscriber !== undefined) {
        return isSubscriber;
      }
      return new Promise(resolve => {
        setTimeout(() => {
          // Change this to true if you want to test what subscribers would see.
          window.isSubscriber = false;
          resolve(window.isSubscriber);
        }, 1000);
      });
    }
  </script>
</head>

以下範例說明如何使用 googlefc.controlledMessagingFunction，只向非訂閱者顯示訊息。

<head>
  <script>
    // Define googlefc and the controlled messaging function on the Window.
    window.googlefc = window.googlefc || {};
    googlefc.controlledMessagingFunction = async (message) => {
      // Determine if the user is a subscriber asynchronously.
      const isSubscriber = await determineIfUserIsSubscriber();

      if (isSubscriber) {
        // If the user is a subscriber, don't show any messages.
        message.proceed(false);
      } else {
        // Otherwise, show messages as usual.
        message.proceed(true);
      }
    }
  </script>
</head>

透過「優惠牆」封閉 Beta 版，發布商可以提供額外參數給 message.proceed()，藉此只封鎖優惠牆。這個參數是 googlefc.MessageTypeEnum 類型的 Array。目前唯一支援的列舉是 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`	資料流可以取得資料流時，系統會執行使用 `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 TCF 第 2 版 API 時，才會叫用相應的回呼。此操作應與 IAB「資訊公開和同意聲明架構第 2 版」的 '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 第 2 版 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_READY 或 CONSENT_DATA_READY 回呼佇列金鑰，確保在叫用回呼時，可以呼叫 IAB GPP API 並傳回同意聲明資料。

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

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

採用 Google 同意聲明管理解決方案的 CPRA 架構 (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>