與 gtag 類似,Google Analytics (分析) 4 使用 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[] | 字串陣列 | 使用者的電話號碼 (經過雜湊處理和編碼)。
將程式碼正規化,例如:
|
user_data.address[] | 陣列 | 根據實際位置識別使用者。 |
user_data.address[].sha256_first_name | 字串 | 使用者的名字 (經過雜湊處理和編碼)。
將程式碼正規化,例如:
|
user_data.address[].sha256_last_name | 字串 | 使用者的姓氏 (經過雜湊處理和編碼)。
將程式碼正規化,例如:
|
user_data.address[].sha256_street | 字串 | 經過雜湊處理和編碼的街道和使用者號碼。
將程式碼正規化,例如:
|
user_data.address[].city | 字串 | 使用者地址的城市。
將程式碼正規化,例如:
|
user_data.address[].region | 字串 | 使用者地址的州或地域。
將程式碼正規化,例如:
|
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
}]
}
})
});