本文適用於在使用 Google 代碼管理工具 (GTM) 的網站上維護同意聲明管理解決方案的開發人員。
本頁面將介紹 Google 代碼管理工具中的同意聲明類型,並說明如何將這些類型與同意聲明管理解決方案整合。
為什麼要使用代碼範本收集同意聲明?
提供代碼範本後,使用者就能以無程式碼的方式整合同意聲明解決方案,大幅節省時間和精力。
使用者可以使用同意聲明模式範本設定預設同意聲明狀態,並將訪客的同意聲明選項傳達給 Google 代碼管理工具。這可確保 Google 和第三方代碼 (支援同意模式) 的最佳運作情形。
範本建立者可以導入同意聲明模式範本供內部使用,也可以將範本發布至社群範本庫,供大眾使用。提供同意聲明模式範本的同意聲明管理平台 (CMP) 供應商,有機會在同意聲明模式說明文件中列出,並在範本庫挑選工具中列出其範本。
同意聲明狀態和同意聲明類型
Google 和第三方代碼會根據 granted
或 denied
的同意聲明狀態調整儲存行為。並針對下列任一同意聲明類型,內建同意聲明檢查:
同意聲明類型 | 說明 |
---|---|
ad_storage |
啟用與廣告相關的儲存功能 (例如 Cookie)。 |
ad_user_data |
設定同意聲明狀態,指明可否基於線上廣告用途將使用者資料傳送給 Google。 |
ad_personalization |
設定個人化廣告的同意聲明。 |
analytics_storage |
啟用與數據分析 (例如造訪停留時間) 相關的儲存功能 (例如 Cookie)。 |
functionality_storage |
啟用支援網站或應用程式功能 (例如語言設定) 的儲存功能。 |
personalization_storage |
啟用與個人化 (例如推薦影片) 相關的儲存功能。 |
security_storage |
啟用與安全性 (例如驗證、防詐欺和其他使用者保護功能) 相關的儲存功能 |
建立新的同意聲明範本
同意聲明模式會追蹤訪客的同意聲明選項,並透過代碼同意聲明檢查確保代碼行為會據此調整。建立新的同意聲明範本時,請遵循下列最佳做法:
請使用代碼管理工具同意聲明模式 API setDefaultConsentState 和 updateConsentState,而非
gtag consent
。使用「同意聲明初始化 - 所有網頁」觸發條件,在觸發時立即設定預設同意聲明狀態。
CMP 必須盡快向訪客提示,要求他們授予或拒絕所有適用的同意聲明類型。
訪客選擇同意聲明後,CMP 必須傳遞更新的同意聲明狀態。
1. 建立新範本
這個實作方法會使用範本中的一個欄位,來保留預設同意聲明狀態。實作程式碼會讀取該欄位,在執行階段設定預設的同意聲明狀態。針對更新指令,程式碼會嘗試讀取同意聲明解決方案設定的 Cookie,以便儲存訪客同意聲明選項。您也應為
updateConsentState
設定回呼,以便處理訪客尚未做出同意聲明選項,或決定變更同意聲明的情況。
如要建立同意聲明範本,請按照下列步驟操作:
- 登入 Google 代碼管理工具帳戶。
- 在左側導覽面板中選取「範本」。
- 在「代碼範本」窗格中,按一下「新增」。
如要設定預設同意聲明狀態,請按照下列步驟操作:
- 選取「欄位」分頁,然後依序點選「新增欄位」>「參數表格」。
- 將名稱變更為
defaultSettings
。 - 展開欄位。
- 將「顯示名稱」更新為
Default settings
。 - 按一下「新增資料欄」,選擇「文字輸入」,將名稱變更為
region
,然後勾選「規定資料欄值必須重複」方塊。 - 展開資料欄,將顯示名稱變更為
Region (leave blank to have consent apply to all regions)
。括號中的陳述式是範本使用者的說明文件。進一步瞭解如何為不同區域設定同意聲明預設狀態。 - 按一下「新增資料欄」,選擇「文字輸入」,將名稱變更為
granted
。 - 展開資料欄,將顯示名稱變更為
Granted Consent Types (comma separated)
。 - 按一下「新增資料欄」,選擇「文字輸入」,將名稱變更為
denied
。 - 展開資料欄,並將顯示名稱變更為
Denied Consent Types (comma separated)
選用:如要支援廣告資料遮蓋功能,請按照下列步驟操作:
- 按一下「新增欄位」,選擇「核取方塊」,然後將欄位名稱變更為
ads_data_redaction
。 - 將「顯示名稱」更新為
Redact Ads Data
進一步瞭解 Cookie 行為,並遮蓋廣告資料
選用:如何新增透過網址參數傳遞的支援:
- 按一下「Add Field」,選擇「Checkbox」,然後將欄位名稱變更為
url_passthrough
。 - 將「顯示名稱」更新為
Pass through URL parameters
進一步瞭解如何傳遞網址參數
新增實作程式碼的步驟如下:
- 在範本編輯器中開啟「Code」分頁標籤。
- 在下方的程式碼範例中,編輯預留位置欄位。
- 複製程式碼,並用來取代範本編輯器中的固定程式碼。
- 按一下「儲存」即可儲存範本。
// The first two lines are optional, use if you want to enable logging
const log = require('logToConsole');
log('data =', data);
const setDefaultConsentState = require('setDefaultConsentState');
const updateConsentState = require('updateConsentState');
const getCookieValues = require('getCookieValues');
const callInWindow = require('callInWindow');
const gtagSet = require('gtagSet');
const COOKIE_NAME = 'Your_cookie_name';
/*
* Splits the input string using comma as a delimiter, returning an array of
* strings
*/
const splitInput = (input) => {
return input.split(',')
.map(entry => entry.trim())
.filter(entry => entry.length !== 0);
};
/*
* Processes a row of input from the default settings table, returning an object
* which can be passed as an argument to setDefaultConsentState
*/
const parseCommandData = (settings) => {
const regions = splitInput(settings['region']);
const granted = splitInput(settings['granted']);
const denied = splitInput(settings['denied']);
const commandData = {};
if (regions.length > 0) {
commandData.region = regions;
}
granted.forEach(entry => {
commandData[entry] = 'granted';
});
denied.forEach(entry => {
commandData[entry] = 'denied';
});
return commandData;
};
/*
* Called when consent changes. Assumes that consent object contains keys which
* directly correspond to Google consent types.
*/
const onUserConsent = (consent) => {
const consentModeStates = {
ad_storage: consent['adConsentGranted'] ? 'granted' : 'denied',
ad_user_data: consent['adUserDataConsentGranted'] ? 'granted' : 'denied',
ad_personalization: consent['adPersonalizationConsentGranted'] ? 'granted' : 'denied',
analytics_storage: consent['analyticsConsentGranted'] ? 'granted' : 'denied',
functionality_storage: consent['functionalityConsentGranted'] ? 'granted' : 'denied',
personalization_storage: consent['personalizationConsentGranted'] ? 'granted' : 'denied',
security_storage: consent['securityConsentGranted'] ? 'granted' : 'denied',
};
updateConsentState(consentModeStates);
};
/*
* Executes the default command, sets the developer ID, and sets up the consent
* update callback
*/
const main = (data) => {
/*
* Optional settings using gtagSet
*/
gtagSet('ads_data_redaction', data.ads_data_redaction);
gtagSet('url_passthrough', data.url_passthrough);
gtagSet('developer_id.your_developer_id', true);
// Set default consent state(s)
data.defaultSettings.forEach(settings => {
const defaultData = parseCommandData(settings);
// wait_for_update (ms) allows for time to receive visitor choices from the CMP
defaultData.wait_for_update = 500;
setDefaultConsentState(defaultData);
});
// Check if cookie is set and has values that correspond to Google consent
// types. If it does, run onUserConsent().
const settings = getCookieValues(COOKIE_NAME);
if (typeof settings !== 'undefined') {
onUserConsent(settings);
}
/**
* Add event listener to trigger update when consent changes
*
* References an external method on the window object which accepts a
* function as an argument. If you do not have such a method, you will need
* to create one before continuing. This method should add the function
* that is passed as an argument as a callback for an event emitted when
* the user updates their consent. The callback should be called with an
* object containing fields that correspond to the five built-in Google
* consent types.
*/
callInWindow('addConsentListenerExample', onUserConsent);
};
main(data);
data.gtmOnSuccess();
接著,請設定存取同意聲明狀態和 Cookie 的權限。
如要新增用於管理同意聲明狀態的權限,請按照下列步驟操作:
- 選取「權限」分頁標籤,然後按一下「存取同意狀態」。
- 按一下「新增同意聲明類型」。
- 按一下方塊,然後在下拉式選單中選取「
ad_storage
」。 - 勾選「Write」。
- 按一下「新增」。
- 針對
ad_user_data
、ad_personalization
和analytics_storage
重複執行步驟 2 到 5。如果需要其他同意聲明類型,請以相同方式新增。 - 按一下 [儲存]。
如要新增存取 Cookie 的權限,請按照下列步驟操作:
- 選取「權限」分頁標籤,然後點選「讀取 Cookie 值」。
- 在「Specific」下方,輸入程式碼需要讀取的每個 Cookie 名稱,以決定使用者的同意選項,每行一個名稱。
- 按一下 [儲存]。
2. 建立單元測試
如要進一步瞭解如何為範本建立測試,請參閱「測試」。
3. 將範本與同意聲明解決方案整合
以下程式碼示範如何透過新增事件監聽器,將此範本與同意聲明管理解決方案的程式碼整合:
// Array of callbacks to be executed when consent changes
const consentListeners = [];
/**
* Called from GTM template to set callback to be executed when user consent is provided.
* @param {function} Callback to execute on user consent
*/
window.addConsentListenerExample = (callback) => {
consentListeners.push(callback);
};
/**
* Called when user grants/denies consent.
* @param {Object} Object containing user consent settings.
*/
const onConsentChange = (consent) => {
consentListeners.forEach((callback) => {
callback(consent);
});
};
更新同意聲明狀態
網站訪客通常會透過與同意聲明橫幅互動,表明同意聲明設定後,範本程式碼應使用 updateConsentState API 相應更新同意聲明狀態。
以下例子顯示,訪客的 updateConsentState
呼叫表示同意存取所有儲存空間類型。同樣地,這個範例會使用 granted
的硬式編碼值,但實際上,這些值應在執行階段使用 CMP 收集的訪客同意聲明來決定。
const updateConsentState = require('updateConsentState');
updateConsentState({
'ad_storage': 'granted',
'ad_user_data': 'granted',
'ad_personalization': 'granted',
'analytics_storage': 'granted',
'functionality_storage': 'granted',
'personalization_storage': 'granted',
'security_storage': 'granted'
});
關於區域專屬行為
如要設定適用於特定地區訪客的預設同意聲明狀態,請在範本中指定區域 (依據 ISO 3166-2)。使用區域值可讓範本使用者遵守地區法規,而不會失去來自這些地區外訪客的資訊。如果在 setDefaultConsentState
指令中未指定區域,則該值會套用至所有其他區域。
舉例來說,以下設定會將 analytics_storage
的預設狀態設為 denied
,適用於西班牙和阿拉斯加州的訪客,並將 analytics_storage
設為 granted
,適用於所有其他訪客:
const setDefaultConsentState = require('setDefaultConsentState');
setDefaultConsentState({
'analytics_storage': 'denied',
'region': ['ES', 'US-AK']
});
setDefaultConsentState({
'analytics_storage': 'granted'
});
最精確的設定優先採用
如果同一個網頁上有兩個預設同意聲明指令,且分別指定區域和子區域的值,則會套用更明確區域的指令。舉例來說,如果您將 ad_storage
設為地區 US
的 'granted'
,並將 ad_storage
設為地區 US-CA
的 'denied'
,來自加州的訪客將會套用更精確的 US-CA
設定。
區域 | ad_storage |
行為 |
---|---|---|
美國 | 'granted' |
適用於美國境內「非」加州的使用者 |
US-CA | 'denied' |
適用於美國-加州使用者 |
未指定 | 'granted' |
使用預設值 'granted' 。在這個範例中,這項設定適用於位於美國以外或美國加州以外的使用者 |
其他中繼資料
您可以使用 gtagSet API 設定下列選用參數:
這些 API 僅適用於 GTM 範本沙箱環境。
透過網址傳送廣告點擊、用戶端 ID 和工作階段 ID 資訊
當訪客按下廣告後前往廣告客戶的網站時,系統可能會將廣告相關資訊加至到達網頁網址,做為查詢參數。為提高轉換準確度,Google 代碼通常會將這項資訊儲存在廣告客戶網域的第一方 Cookie 中。
不過,如果 ad_storage
為 denied
,Google 代碼就不會在本機儲存這項資訊。在這種情況下,廣告客戶可以使用「網址傳送」功能,選擇透過網址參數在各個網頁中傳遞廣告點擊資訊。
同樣地,如果 analytics_storage
設為拒絕,您就可以使用網址傳送功能,在各個網頁中傳送事件和以工作階段為基礎的數據分析資料 (包括轉換),而不需要使用 Cookie。
您必須符合下列條件,才能使用網址直通功能:
- 網頁上有同意聲明認知的 Google 代碼。
- 網站已選擇使用網址穿透功能。
- 網頁已導入同意聲明模式。
- 出站連結指的是與目前網頁網域相同的網域。
- 網址中含有 gclid/dclid (僅限 Google Ads 和 Floodlight 代碼)
您的範本應允許範本使用者設定是否要啟用這項設定。以下範本程式碼可用來將 url_passthrough 設為 true:
gtagSet('url_passthrough', true);
遮蓋廣告資料
當 ad_storage
遭到拒絕時,系統就不會為廣告目的設定新的 Cookie。此外,系統不會使用先前在 google.com 和 doubleclick.net 上設定的第三方 Cookie。傳送給 Google 的資料仍會包含完整網頁網址,包括網址參數中的任何廣告點擊資訊。
如要在 ad_storage
遭拒時進一步遮蓋廣告資料,請將 ads_data_redaction
設為 true。
如果 ads_data_redaction
為 true 且 ad_storage
遭拒,Google Ads 和 Floodlight 代碼在網路要求中傳送的廣告點擊 ID 會遭到遮蓋。
gtagSet('ads_data_redaction', true);
開發人員 ID
如果您是擁有 Google 核發開發人員 ID 的 CMP 供應商,請盡快在範本中使用下列方法設定這項資訊。
如果實作項目會由不相關的公司或實體在多個網站上使用,您只需要提供開發人員 ID。如果實作項目只會由一個網站或實體使用,請勿申請開發人員 ID。
gtagSet('developer_id.<your_developer_id>', true);
為使用者提供文件
您的使用者會使用您的同意聲明範本,設定收集使用者同意聲明的代碼。請提供使用者說明文件,瞭解下列最佳做法:
- 如何在「設定」表格中設定同意聲明預設狀態。
- 如何新增其他表格資料列,為不同區域設定同意聲明預設值。
- 在「Consent Initialization - All Pages」觸發條件上觸發代碼。
後續步驟
如果您要提供範本給所有代碼管理工具使用者,請將其上傳至社群範本庫。