使用 Measurement Protocol 一并发送用户提供的数据及 User-ID

与使用 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 POST 正文

键 类型 说明
user_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 字符串 经过哈希处理和编码的用户名字。按照以下要求进行标准化：
  • 移除数字和符号字符
  • 小写
  • 移除开头和结尾处的空格
  • 使用 SHA256 算法进行哈希处理
  • 使用十六进制字符串格式进行编码。
user_data.address[].sha256_last_name 字符串 经过哈希处理和编码的用户姓氏。按照以下要求进行标准化：
  • 移除数字和符号字符
  • 小写
  • 移除开头和结尾处的空格
  • 使用 SHA256 算法进行哈希处理
  • 使用十六进制字符串格式进行编码。
user_data.address[].sha256_street 字符串 经过哈希处理和编码的用户地址中的街道名称和门牌号。按照以下要求进行标准化：
  • 移除符号字符
  • 小写
  • 移除开头和结尾处的空格
  • 使用 SHA256 算法进行哈希处理
  • 使用十六进制字符串格式进行编码。
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 要求开发者在调用 API 之前，先采用名为 SHA256 的单向安全哈希算法对用户提供的敏感数据进行哈希处理，并使用十六进制字符串格式对这些数据进行编码。

名称以 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
      }]
    }
  })
});