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

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

簡介

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

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

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

使用 IAB 資訊公開和同意聲明架構第 2 版規格取得 GDPR 同意聲明
依 IAB GPP CPRA 規格選擇停用 CPRA

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

幾種方法可以在網站上部署這項使用者訊息功能，方式：

大多數情況下，您不需要重新加上現有的 Google 發布端標記或 AdSense 代碼部署訊息發布至相關產品後的使用者訊息。
如果您使用廣告封鎖復原訊息，則必須新增廣告封鎖代碼請參閱廣告管理員和 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`	函式(!Object)	此函式可決定是否繼續傳送訊息。這項功能適用於所有訊息類型。
`googlefc.callbackQueue`	!Array<!Object<string, function()>>\|!Array<function()>\|!googlefc.CallbackQueue	這是非同步執行使用者訊息查詢的回呼佇列的參照。
`googlefc.CallbackQueue`	!Object	回呼佇列物件的類型。
`googlefc.AdBlockerStatusEnum`	!Object<字串, 數字>	代表使用者廣告攔截器狀態的列舉。
`googlefc.AllowAdsStatusEnum`	!Object<字串, 數字>	列舉代表使用者 allow-ads 狀態的列舉。
`googlefc.ccpa.InitialCcpaStatusEnum`	!Object<字串, 數字>	列舉使用者初始 CPRA 狀態的列舉。
`googlefc.ccpa.overrideDnsLink`	未定義\|布林值	布林值，可設為 true 以使用自訂「不要銷售」連結。

方法摘要

名稱	傳回類型	定義
`googlefc.showRevocationMessage()`	未定義	清除同意聲明記錄並重新載入 `googlefc` 指令碼，以便顯示適合使用者的同意授權訊息。
`googlefc.getAdBlockerStatus()`	號碼	根據使用者的廣告封鎖狀態，在 `AdBlockerStatusEnum` 中傳回值。
`googlefc.getAllowAdsStatus()`	號碼	根據使用者的 allow-ads 狀態，傳回 `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 封閉測試版，藉此指定只應使用 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` 執行推送至回呼佇列的函式。請注意，後續只要直接呼叫 US Privacy API (`__uspapi`) 即可取得 CPRA 資料的任何後續要求。	中

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}

如果預設的「不要銷售」連結為已覆寫。使用者與確認對話方塊互動後，系統會提供如果使用者決定停用，即會使用 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 同意聲明管理工具收集 GDPR 同意聲明採用 IAB「資訊公開和同意聲明架構第 2 版」架構時，則應使用 IAB 資訊公開和同意聲明架構第 2 版 API。

您可以使用 CONSENT_API_READY 回呼佇列金鑰，確保只在是否已在網頁上定義 IAB 資訊公開和同意聲明架構第 2 版 API。這應該使用 'addEventListener'敬上整合了 IAB 資訊公開和同意聲明架構第 2 版 API

範例：

<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'敬上 command - 首次叫用提供的回呼時提供的資料會包含使用者的同意聲明選項 (前提是資訊公開和同意聲明架構第 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>

搭配 CPRA 的 IAB GPP 架構使用 Google 同意聲明管理解決方案

如果您使用 Google 同意聲明管理工具收集 CPRA 選擇不採用選項執行 IAB GPP 架構時，則應使用 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 的 IAB GPP 架構

如果您使用 Google 同意聲明管理工具收集 CPRA 選擇不採用選項根據 IAB GPP 架構，您或許可以提供自訂「不要銷售」的連結將 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 確認對話方塊來販售連結。

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