簡介
這個 API 提供工具,讓您與「隱私權與訊息」分頁提供的訊息互動。也可以執行下列操作:
- 禁止任何特定使用者收發訊息
- 查詢使用者的廣告封鎖狀態
- 允許使用者撤銷同意聲明 (如適用)
您也可以使用這些工具,透過某些業界標準通訊協定收集使用者同意聲明:
- 採用 IAB 資訊公開和同意聲明架構第 2 版規格的 GDPR 同意聲明
- 根據 IAB GPP CPRA 規格選擇停用 CPRA
在這種情況下,系統會透過這些 API 傳遞同意聲明狀態。
您可以透過下列幾種方式在網站上部署這項使用者訊息功能:
- 在大部分情況下,您不需要重新標記。只要使用現有的 Google 發布商廣告代碼或 AdSense 廣告代碼,當訊息發布到相關產品後,系統就會部署使用者訊息。
- 如果您使用廣告封鎖復原訊息,則必須在網頁中明確加入廣告封鎖代碼。詳情請參閱 Ad Manager 和 AdSense 標記操作說明。
googlefc
是使用者訊息功能針對 JavaScript Window
上的 API 使用的全域命名空間。
欄位摘要
名稱 | 類型 | 定義 |
---|---|---|
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>
對訊息相關呼叫非同步執行作業的全域回呼佇列的參照。叫用任何函式的唯一支援方式是將函式新增至 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>
針對 GDPR 使用 IAB 資訊公開和同意聲明架構第 2 版,使用 Google 同意聲明管理解決方案
如果您使用 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>