建立同意聲明模式範本

本文適用於在使用 Google 代碼管理工具 (GTM) 的網站上維護同意聲明管理解決方案的開發人員。

本頁面將介紹 Google 代碼管理工具中的同意聲明類型，並說明如何將這些類型與同意聲明管理解決方案整合。

為什麼要使用代碼範本收集同意聲明？

提供代碼範本後，使用者就能以無程式碼的方式整合同意聲明解決方案，大幅節省時間和精力。

使用者可以使用同意聲明模式範本設定預設同意聲明狀態，並將訪客的同意聲明選項傳達給 Google 代碼管理工具。這可確保 Google 和第三方代碼 (支援同意模式) 的最佳運作情形。

範本建立者可以導入同意聲明模式範本供內部使用，也可以將範本發布至社群範本庫，供大眾使用。提供同意聲明模式範本的同意聲明管理平台 (CMP) 供應商，有機會在同意聲明模式說明文件中列出，並在範本庫挑選工具中列出其範本。

請勿建立使用 gtag consent 指令的範本。請改用代碼管理工具 API updateConsentState。gtag 指令會在所有其他待處理訊息之後排入佇列，且可能不會在下一個事件開始前處理。詳情請參閱「 資料層資訊的處理方式」。

同意聲明管理平台 (CMP) 通常是指供應商提供的同意聲明管理解決方案，本頁面使用「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。

  重要事項： gtag 指令會在所有其他待處理訊息之後排入佇列，且可能不會在下一個事件開始前處理。詳情請參閱「資料層資訊的處理方式」。

• 使用「同意聲明初始化 - 所有網頁」觸發條件，在觸發時立即設定預設同意聲明狀態。

• CMP 必須盡快向訪客提示，要求他們授予或拒絕所有適用的同意聲明類型。

• 訪客選擇同意聲明後，CMP 必須傳遞更新的同意聲明狀態。

1. 建立新範本

這個實作方法會使用範本中的一個欄位，來保留預設同意聲明狀態。實作程式碼會讀取該欄位，在執行階段設定預設的同意聲明狀態。針對更新指令，程式碼會嘗試讀取同意聲明解決方案設定的 Cookie，以便儲存訪客同意聲明選項。您也應為 updateConsentState 設定回呼，以便處理訪客尚未做出同意聲明選項，或決定變更同意聲明的情況。

如要建立同意聲明範本，請按照下列步驟操作：

1. 登入 Google 代碼管理工具帳戶。
2. 在左側導覽面板中選取「範本」。
3. 在「代碼範本」窗格中，按一下「新增」。

如要設定預設同意聲明狀態，請按照下列步驟操作：

1. 選取「欄位」分頁，然後依序點選「新增欄位」>「參數表格」。
2. 將名稱變更為 defaultSettings。
3. 展開欄位。
4. 將「顯示名稱」更新為 Default settings。
5. 按一下「新增資料欄」，選擇「文字輸入」，將名稱變更為 region，然後勾選「規定資料欄值必須重複」方塊。
6. 展開資料欄，將顯示名稱變更為 Region (leave blank to have consent apply to all regions)。括號中的陳述式是範本使用者的說明文件。進一步瞭解如何為不同區域設定同意聲明預設狀態。
7. 按一下「新增資料欄」，選擇「文字輸入」，將名稱變更為 granted。
8. 展開資料欄，將顯示名稱變更為 Granted Consent Types (comma separated)。
9. 按一下「新增資料欄」，選擇「文字輸入」，將名稱變更為 denied。
10. 展開資料欄，並將顯示名稱變更為 Denied Consent Types (comma separated)

選用：如要支援廣告資料遮蓋功能，請按照下列步驟操作：

1. 按一下「新增欄位」，選擇「核取方塊」，然後將欄位名稱變更為 ads_data_redaction。
2. 將「顯示名稱」更新為 Redact Ads Data

進一步瞭解 Cookie 行為，並遮蓋廣告資料

選用：如何新增透過網址參數傳遞的支援：

1. 按一下「Add Field」，選擇「Checkbox」，然後將欄位名稱變更為 url_passthrough。
2. 將「顯示名稱」更新為 Pass through URL parameters

進一步瞭解如何傳遞網址參數

新增實作程式碼的步驟如下：

1. 在範本編輯器中開啟「Code」分頁標籤。
2. 在下方的程式碼範例中，編輯預留位置欄位。
3. 複製程式碼，並用來取代範本編輯器中的固定程式碼。
4. 按一下「儲存」即可儲存範本。

注意： 第一次儲存程式碼時，系統會發生驗證錯誤。您稍後在「Permissions」分頁中新增 Cookie 名稱後，這項問題就會解決。

// 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 的權限。

如要新增用於管理同意聲明狀態的權限，請按照下列步驟操作：

1. 選取「權限」分頁標籤，然後按一下「存取同意狀態」。
2. 按一下「新增同意聲明類型」。
3. 按一下方塊，然後在下拉式選單中選取「ad_storage」。
4. 勾選「Write」。
5. 按一下「新增」。
6. 針對 ad_user_data、ad_personalization 和 analytics_storage 重複執行步驟 2 到 5。如果需要其他同意聲明類型，請以相同方式新增。
7. 按一下 [儲存]。

如要新增存取 Cookie 的權限，請按照下列步驟操作：

1. 選取「權限」分頁標籤，然後點選「讀取 Cookie 值」。
2. 在「Specific」下方，輸入程式碼需要讀取的每個 Cookie 名稱，以決定使用者的同意選項，每行一個名稱。
3. 按一下 [儲存]。

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 呼叫。盡可能使用範本的沙箱程式碼，直接從儲存同意聲明的 Cookie 讀取使用者同意聲明，而非使用外部程式碼執行這項操作。如果在呼叫 updateConsentState 之前需要發出網路要求或執行其他非同步工作，請在呼叫 setDefaultConsentState 時，在 wait_for_update 欄位中指定至少 500 毫秒的等待時間。這樣一來，這些工作就能在 Google 代碼觸發前完成。詳情請參閱「與非同步同意聲明管理平台整合」一文。

以下例子顯示，訪客的 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 設定下列選用參數：

• url_passthrough
• ads_data_redaction
• developer_id

這些 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」觸發條件上觸發代碼。

後續步驟

如果您要提供範本給所有代碼管理工具使用者，請將其上傳至社群範本庫。