Gửi dữ liệu do người dùng cung cấp kèm theo User-ID bằng Measurement Protocol

Tương tự như việc sử dụng gtag, có thể dùng Measurement Protocol của Google Analytics để gửi dữ liệu do người dùng cung cấp cùng với User-ID. Dữ liệu này có thể được dùng để cải thiện đo lường lượt chuyển đổi và hành vi.

Để gửi dữ liệu do người dùng cung cấp cùng với yêu cầu Measurement Protocol, hãy thêm phương thức Tham số user_data trong tải trọng JSON. Tham số user_id phải là sẽ hiển thị bất cứ khi nào user_data được cung cấp.

Measurement Protocol đang sử dụng cùng một thuật toán chuẩn hoá và băm với tư cách là Đo lường nâng cao qua API Google Ads của chúng tôi. Đối với vấn đề về quyền riêng tư, địa chỉ email, số điện thoại, tên, họ, và địa chỉ đường phố phải được băm bằng hàm Thuật toán SHA-256 trước đang được tải lên. Giá trị đã băm phải được mã hoá theo định dạng chuỗi hex (chuỗi đối tượng chỉ chứa chữ số thập lục phân), chẳng hạn như 88d7ecb5c5b21d7b1.

Để chuẩn hoá kết quả băm, trước khi băm một trong bạn phải:

  • Xoá khoảng trắng ở đầu và cuối.
  • Chuyển đổi văn bản thành chữ thường.
  • Định dạng số điện thoại theo Tiêu chuẩn E164.
  • Xoá tất cả dấu chấm (.) đứng trước tên miền trong gmail.comgooglemail.com địa chỉ email.

Nội dung của bài đăng JSON

Khoá Loại Mô tả
user_id string Giá trị nhận dạng duy nhất của người dùng. Hãy xem bài viết User-ID cho bản phân tích trên nhiều nền tảng để biết thêm thông tin về giá trị nhận dạng này.
user_data đối tượng Các trường dữ liệu người dùng nâng cao sẽ nhận dạng người dùng.
user_data.sha256_email_address[] mảng chuỗi Địa chỉ email đã băm và mã hoá của người dùng. Được chuẩn hoá như sau:
user_data.sha256_phone_number[] mảng chuỗi Số điện thoại đã băm và mã hoá của người dùng. Được chuẩn hoá như sau:
  • xoá tất cả ký tự không phải chữ số
  • thêm tiền tố +
  • hàm băm bằng thuật toán SHA256
  • mã hoá bằng định dạng chuỗi hex.
user_data.address[] mảng Xác định người dùng dựa trên vị trí thực tế.
user_data.address[].sha256_first_name string Tên đã băm và mã hoá của người dùng. Được chuẩn hoá như sau:
  • xoá chữ số và ký tự biểu tượng
  • chữ thường
  • xóa dấu cách ở đầu và cuối
  • hàm băm bằng thuật toán SHA256
  • mã hoá bằng định dạng chuỗi hex.
user_data.address[].sha256_last_name string Họ đã băm và mã hoá của người dùng. Được chuẩn hoá như sau:
  • xoá chữ số và ký tự biểu tượng
  • chữ thường
  • xóa dấu cách ở đầu và cuối
  • hàm băm bằng thuật toán SHA256
  • mã hoá bằng định dạng chuỗi hex.
user_data.address[].sha256_street string Đường phố và số người dùng đã băm và được mã hoá. Được chuẩn hoá như sau:
  • xoá ký tự biểu tượng
  • chữ thường
  • xóa dấu cách ở đầu và cuối
  • hàm băm bằng thuật toán SHA256
  • mã hoá bằng định dạng chuỗi hex.
user_data.address[].city string Thành phố cho địa chỉ của người dùng. Được chuẩn hoá như sau:
  • xoá chữ số và ký tự biểu tượng
  • chữ thường
  • xoá các dấu cách ở đầu và cuối.
user_data.address[].region string Tiểu bang hoặc lãnh thổ trong địa chỉ của người dùng. Được chuẩn hoá như sau:
  • xoá chữ số và ký tự biểu tượng
  • chữ thường
  • xoá các dấu cách ở đầu và cuối.
user_data.address[].postal_code string Mã bưu chính cho địa chỉ của người dùng. Được chuẩn hoá như sau:
  • xoá .~ ký tự
  • xoá các dấu cách ở đầu và cuối.
user_data.address[].country string Mã quốc gia cho địa chỉ của người dùng. Được định dạng theo tiêu chuẩn ISO 3166-1 alpha-2.

Xem Tài liệu tham khảo về Measurement Protocol để biết thêm thông tin về cách định dạng phương thức vận chuyển và tải trọng.

Gửi dữ liệu do người dùng cung cấp

Không giống như gtag tự động băm dữ liệu nhạy cảm do người dùng cung cấp, Measurement Protocol yêu cầu nhà phát triển băm dữ liệu nhạy cảm do người dùng cung cấp bằng phương thức mã một chiều bảo mật thuật toán băm được gọi SHA256 và mã hoá quảng cáo đó bằng định dạng chuỗi hex trước khi gọi API.

Tất cả các trường dữ liệu người dùng bắt đầu bằng tiền tố sha256 trong tên đều phải là chỉ được điền sẵn các giá trị đã băm và được mã hoá theo hệ thập lục phân.

Mã ví dụ sau đây sẽ thực hiện các bước mã hoá và mã hoá cần thiết:

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));

Một lối tắt thuận tiện cho phép bạn sử dụng tất cả các trường lặp lại bên trong đối tượng user_data (chẳng hạn như address, sha256_email_address, sha256_phone_number) có thể là đã chuyển một giá trị số ít thay vì một mảng.

Mã mẫu sau đây gọi Measurement Protocol và chuyển dữ liệu người dùng cùng với 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
      }
    }
  })
});

Nhiều giá trị

Nhà phát triển có thể tuỳ ý cung cấp nhiều giá trị (tối đa 3 giá trị cho số điện thoại và email và 2 cho địa chỉ) bằng cách sử dụng giá trị mảng thay vì giá trị chuỗi. Nếu bạn chụp nhiều hơn một giá trị, nên việc này sẽ làm tăng khả năng trùng khớp.

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