使用 Measurement Protocol 傳送使用者提供的資料

與使用 gtag 類似，您可以透過 Google Analytics Measurement Protocol 連同 User-ID 傳送使用者提供的資料，用於改善行為和轉換評估成效。

如要連同 Measurement Protocol 要求傳送使用者提供的資料，請在 JSON 酬載中新增 user_data 參數。如果提供 user_data，建議一併加入 user_id 參數。確保評估結果最準確，並讓功能正常運作。

Measurement Protocol 使用的常態化和雜湊演算法，與 Google Ads API 強化評估功能相同。基於隱私權疑慮，電子郵件地址、電話號碼、名字、姓氏和街道地址必須使用 SHA-256 演算法進行雜湊處理，才能上傳。雜湊值應以十六進位字串格式編碼 (僅含十六進位數字的字串物件)，例如 88d7ecb5c5b21d7b1。

為了使雜湊處理結果標準化，在對其中任何值進行雜湊處理前，您必須先完成下列事項：

  • 移除開頭和結尾的空白字元。
  • 將文字轉換為小寫。
  • 根據 E164 標準設定電話號碼格式。
  • 移除 gmail.com 和 googlemail.com 電子郵件地址中網域名稱前的所有半形句號 (.)。

JSON 貼文內文

鍵 類型 說明
user_id (選用，但建議使用) 字串 使用者的專屬 ID。如要進一步瞭解這個 ID，請參閱「跨平台分析的 User-ID」。
user_data 物件 可識別使用者的強化使用者資料欄位。
user_data.sha256_email_address[] 字串陣列 < 經雜湊處理及編碼的使用者電子郵件地址。 正規化後如下：
user_data.sha256_phone_number[] 字串陣列 經雜湊處理和編碼的使用者電話號碼。 正規化後如下：
  • 移除所有非數字字元
  • 新增 + 前置字串
  • 使用 SHA256 演算法進行雜湊處理
  • 以十六進位字串格式編碼。
user_data.address[] 陣列 根據實際位置識別使用者。
user_data.address[].sha256_first_name 字串 <0x 經雜湊處理和編碼的使用者名字。 正規化後如下：
  • 移除數字和符號字元
  • lowercase
  • 移除開頭和結尾的空格
  • 使用 SHA256 演算法進行雜湊處理
  • 以十六進位字串格式編碼。
user_data.address[].sha256_last_name 字串 <0x 經雜湊處理和編碼的使用者姓氏。 正規化後如下：
  • 移除數字和符號字元
  • lowercase
  • 移除開頭和結尾的空格
  • 使用 SHA256 演算法進行雜湊處理
  • 以十六進位字串格式編碼。
user_data.address[].sha256_street 字串 <0x 經雜湊處理和編碼的使用者街道和號碼。 正規化後如下：
  • 移除符號字元
  • lowercase
  • 移除開頭和結尾的空格
  • 使用 SHA256 演算法進行雜湊處理
  • 以十六進位字串格式編碼。
user_data.address[].city 字串 <0x 使用者地址所在的城市。 正規化後如下：
  • 移除數字和符號字元
  • lowercase
  • 移除開頭和結尾的空格。
user_data.address[].region 字串 <0x 使用者的地址所在的州/省或地域。 正規化後如下：
  • 移除數字和符號字元
  • lowercase
  • 移除開頭和結尾的空格。
user_data.address[].postal_code 字串 使用者的地址郵遞區號。 正規化後如下：
  • 移除 . 和 ~ 字元
  • 移除開頭和結尾的空格。
user_data.address[].country 字串 使用者地址的國家/地區代碼。格式符合 ISO 3166-1 alpha-2 標準。

如要進一步瞭解傳輸和酬載的格式，請參閱 Measurement Protocol 參考文件。

傳送使用者提供的資料

與會自動雜湊處理敏感使用者提供資料的 gtag 不同，Measurement Protocol 要求開發人員先使用安全的單向雜湊演算法 (稱為 SHA256) 雜湊處理敏感使用者提供資料，再以十六進位字串格式編碼，然後才呼叫 API。

名稱開頭為 sha256 前置字元的所有使用者資料欄位，都只能填入經過雜湊處理和十六進位編碼的值。

下列程式碼範例會執行必要的加密和編碼步驟：

Node.js

const { subtle } = require('crypto').webcrypto;

async function populateSensitiveUserData(value) {
  const encoder = new TextEncoder();
  // Convert a string value to UTF-8 encoded text.
  const valueUtf8 = encoder.encode(value);
  // Compute the hash (digest) using the SHA-256 algorithm.
  const hashSha256 = await subtle.digest('SHA-256', valueUtf8);
  // Convert buffer to byte array.
  const hashArray = Array.from(new Uint8Array(hashSha256));
  // Return a hex-encoded string.
  return hashArray.map(b => b.toString(16).padStart(2, "0")).join('');
};

// Test the encryption function by calling it.
async function main() {
  return await populateSensitiveUserData('<value>');
}

main()
  .then(v => console.log(v))
  .catch(err => console.error(err));

為方便起見，user_data 物件內的所有重複欄位 (例如 address、sha256_email_address、sha256_phone_number) 都可以傳遞單一值，而非陣列。

下列程式碼範例會呼叫 Measurement Protocol，並傳遞使用者資料和 User-ID。

Node.js

const measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

// Populate mock User Data using the `populateSensitiveUserData` function defined
// above.
const yourEmailSha256Variable = await populateSensitiveUserData('test@yourdomain.com');
const