使用 Measurement Protocol，以 User-ID 傳送使用者提供的資料

與使用 gtag 類似， 可使用 Google Analytics Measurement Protocol 傳送「使用者提供的資料」和「User-ID」，可用於改善 行為及轉換評估

如要隨 Measurement Protocol 要求傳送使用者提供的資料，請新增 JSON 酬載中的 user_data 參數。user_id 參數必須 但會在提供 user_data 時出現。

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 字串 使用者的名字經過雜湊處理並編碼。 已正規化，例如：
  • 移除數字和符號字元
  • lowercase
  • 移除開頭和結尾的空格
  • 使用 SHA256 演算法進行雜湊
  • 以十六進位字串格式進行編碼
user_data.address[].sha256_last_name 字串 使用者的姓氏經過雜湊處理並編碼。 已正規化，例如：
  • 移除數字和符號字元
  • lowercase
  • 移除開頭和結尾的空格
  • 使用 SHA256 演算法進行雜湊
  • 以十六進位字串格式進行編碼
user_data.address[].sha256_street 字串 雜湊及編碼的街道和使用者號碼。 已正規化，例如：
  • 移除符號字元
  • lowercase
  • 移除開頭和結尾的空格
  • 使用 SHA256 演算法進行雜湊
  • 以十六進位字串格式進行編碼
user_data.address[].city 字串 使用者地址的城市。 已正規化，例如：
  • 移除數字和符號字元
  • lowercase
  • 移除開頭和結尾的空格
user_data.address[].region 字串 使用者地址的州/省或地域。 已正規化，例如：
  • 移除數字和符號字元
  • 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 value_utf8 = encoder.encode(value);
  // Compute the hash (digest) using the SHA-256 algorithm.
  const hash_sha256 = await subtle.digest('SHA-256', value_utf8);
  // Convert buffer to byte array.
  const hash_array = Array.from(new Uint8Array(hash_sha256));
  // Return a hex-encoded string.
  return hash_array.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 measurement_id = 'G-XXXXXXXXXX';
const api_secret = '<secret_value>';

// Populate mock User Data using the `populateSensitiveUserData` function defined
// above.
const yourEmailSha256Variable = await populateSensitiveUserData('test@yourdomain.com');
const yourPhoneSha256Variable  = await populateSensitiveUserData('+15555555555');
const yourFirstNameSha256Variable  = await populateSensitiveUserData('john');
const yourLastNameSha256Variable  = await populateSensitiveUserData('doe');
const yourStreetAddressSha256Variable  = await populateSensitiveUserData('123 main street');

// Populate mock unencrypted user data.
const yourCityVariable = 'san francisco';
const yourRegionVariable = 'california';
const yourPostalCodeVariable = '94000';
const yourCountryVariable = 'US';

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: 'XXXXXXXXXX.YYYYYYYYYY',
    user_id: "XXX",
    events: [{
      name: 'purchase'
    }],
    user_data: {
      sha256_email_address: yourEmailSha256Variable,
      sha256_phone_number: yourPhoneSha256Variable,
      address: {
        sha256_first_name: yourFirstNameSha256Variable,
        sha256_last_name: yourLastNameSha256Variable,
        sha256_street: yourStreetAddressSha256Variable,
        city: yourCityVariable,
        region: yourRegionVariable,
        postal_code: yourPostalCodeVariable,
        country: yourCountryVariable
      }
    }
  })
});

多個值

開發人員可以選擇提供多個值 (電話和電子郵件最多 3 個) 和 2 代表地址)，則使用陣列值而非字串。如果擷取 多個值，這樣有助於提高比對成功的機率。

Node.js

const measurement_id = 'G-XXXXXXXXXX';
const api_secret = '<secret_value>';

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: 'XXXXXXXXXX.YYYYYYYYYY',
    user_id: "XXX",
    events: [{
      name: 'purchase'
    }],
    user_data: {
      sha256_email_address: [yourEmailSha256Variable1, yourEmailSha256Variable2],
      sha256_phone_number: [yourPhoneSha256Variable1, yourPhoneSha256Variable2],
      address: [{
        sha256_first_name: yourFirstNameSha256Variable1,
        sha256_last_name: yourLastNameSha256Variable1,
        sha256_street: yourStreetAddressSha256Variable1,
        city: yourCityVariable1,
        region: yourRegionVariable1,
        postal_code: yourPostalCodeVariable1,
        country: yourCountryVariable1
      },{
        sha256_first_name: yourFirstNameSha256Variable2,
        sha256_last_name: yourLastNameSha256Variable2,
        sha256_street: yourStreetAddressSha256Variable2,
        city: yourCityVariable2,
        region: yourRegionVariable2,
        postal_code: yourPostalCodeVariable2,
        country: yourCountryVariable2
      }]
    }
  })
});