本文旨在協助開發人員在使用 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 |
啟用與安全性 (例如驗證、防範詐欺和其他使用者保護措施) 相關的儲存功能 |
建立新的同意聲明範本
同意聲明模式會追蹤訪客同意聲明選項和代碼同意聲明檢查,確保代碼行為能隨之調整。建立新的同意聲明範本時,請遵循最佳做法:
使用 Tag Manager 同意聲明模式 API setDefaultConsentState 和 updateConsentState,而不是
gtag consent
。使用「同意聲明初始化 - 所有網頁」觸發條件啟動時,立即設定預設同意聲明狀態。
CMP 必須盡快提示訪客,針對所有適用的同意聲明類型表示同意或拒絕。
訪客表示同意選項時,同意聲明管理平台必須傳遞已更新的同意聲明狀態。
1. 建立新範本
這種導入方法會使用範本中的一個欄位保留預設的同意聲明狀態。導入程式碼會讀取該欄位,以便在執行階段設定預設同意聲明狀態。針對更新指令,程式碼會嘗試讀取同意聲明解決方案設定的 Cookie,以便儲存訪客同意聲明選項。您還可以為
updateConsentState
設定回呼,處理訪客尚未選擇同意聲明選項或決定變更同意聲明的情況。
如何建立同意聲明範本:
- 登入 Google 代碼管理工具帳戶。
- 選取左側導覽面板中的「範本」。
- 在「Tag Templates」窗格中按一下「New」。
如何設定預設同意聲明狀態:
- 選取「欄位」分頁標籤,然後依序點選「新增欄位」>「參數表格」。
- 將名稱變更為
defaultSettings
。 - 展開欄位。
- 將「Display name」更新為
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)
選用:如要支援廣告資料遮蓋功能,請按照下列步驟操作:
- 按一下「Add Field」,選擇「Checkbox」,然後將欄位名稱變更為
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 值」。
- 在「特定」下方,輸入程式碼需要讀取的每個 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'
});
最明確的優先順序
如果在同一個網頁上出現兩個預設同意聲明指令,且該指令含有區域和子區域的值,則會生效。舉例來說,如果您將 US
區域的 ad_storage
設為 'granted'
,並將 US-CA
區域的 ad_storage
設為 'denied'
,則加州訪客就會生效更具體的 US-CA
設定。
區域 | ad_storage |
行為 |
---|---|---|
美國 | 'granted' |
適用於「不在」加拿大的使用者 |
美國加州 | 'denied' |
適用於 US-CA 的使用者 |
未指定 | 'granted' |
使用預設值 'granted' 。在本例中,位於美國或加拿大以外的使用者 |
其他中繼資料
您可以使用 gtagSet API 設定下列選用參數:
這些 API 只能在 Google 代碼管理工具範本沙箱環境中使用。
在網址中傳遞廣告點擊、用戶端 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);
為使用者提供文件
使用者會使用同意範本設定收集使用者同意聲明的代碼。為使用者提供說明文件,解釋下列最佳做法:
- 如何在「設定」表格中設定同意聲明預設值。
- 如何透過新增額外資料表列,為不同區域設定同意聲明預設值。
- 在「同意聲明初始化 - 所有網頁」觸發條件中觸發代碼。
後續步驟
如要提供範本給所有代碼管理工具使用者,請上傳到社群範本庫。