Mengirim data yang disediakan pengguna dengan User-ID menggunakan Measurement Protocol

Serupa dengan penggunaan gtag, Measurement Protocol Google Analytics untuk Google Analytics 4 dapat digunakan untuk mengirim data yang disediakan pengguna bersama dengan User-ID, yang dapat digunakan untuk meningkatkan akurasi pengukuran konversi dan perilaku.

Untuk mengirim data yang disediakan pengguna bersama dengan permintaan Measurement Protocol, tambahkan parameter user_data di payload JSON. Parameter user_id harus ada setiap kali user_data disediakan.

Measurement Protocol menggunakan normalisasi dan algoritma hashing yang sama seperti fitur Pengukuran yang Ditingkatkan Google Ads API. Untuk masalah privasi, alamat email, nomor telepon, nama depan, nama belakang, dan alamat harus di-hash menggunakan algoritma SHA-256 sebelum diupload. Nilai yang di-hash harus dienkode dalam format string hex (objek string yang berisi hanya digit heksadesimal), seperti 88d7ecb5c5b21d7b1.

Untuk menstandarkan hasil hash, sebelum melakukan hashing pada salah satu nilai berikut, Anda harus:

Menghapus spasi kosong di awal dan akhir.
Mengonversi teks menjadi huruf kecil.
Memformat nomor telepon sesuai dengan standar E164.
Menghapus semua titik (.) yang mendahului nama domain di alamat email gmail.com dan googlemail.com.

Isi JSON POST

Kunci	Jenis	Deskripsi
user_id	string	ID unik untuk pengguna. Lihat artikel User-ID untuk analisis lintas platform guna mendapatkan informasi lebih lanjut tentang ID ini.
user_data	Objek	Kolom data pengguna yang ditingkatkan yang mengidentifikasi pengguna.
user_data.sha256_email_address[]	array string	Alamat email pengguna yang di-hash dan dienkode. Dinormalkan seperti berikut: huruf kecil hapus titik sebelum `@` untuk alamat gmail.com/googlemail.com hapus semua spasi beri hash menggunakan algoritma SHA256 enkode dengan format string hex.
user_data.sha256_phone_number[]	array string	Nomor telepon pengguna yang dienkode dan di-hash. Dinormalkan seperti berikut: hapus semua karakter non-digit tambahkan imbuhan `+` beri hash menggunakan algoritma SHA256 enkode dengan format string hex.
user_data.address[]	array	Mengidentifikasi pengguna berdasarkan lokasi fisik.
user_data.address[].sha256_first_name	string	Nama depan pengguna yang dienkode dan di-hash. Dinormalkan seperti berikut: hapus digit dan karakter simbol huruf kecil hapus spasi di awal dan di akhir beri hash menggunakan algoritma SHA256 enkode dengan format string hex.
user_data.address[].sha256_last_name	string	Nama belakang pengguna yang di-hash dan dienkode. Dinormalkan seperti berikut: hapus digit dan karakter simbol huruf kecil hapus spasi di awal dan di akhir beri hash menggunakan algoritma SHA256 enkode dengan format string hex.
user_data.address[].sha256_street	string	Jalan dan nomor untuk alamat pengguna yang di-hash dan dienkode. Dinormalkan seperti berikut: hapus karakter simbol huruf kecil hapus spasi di awal dan di akhir beri hash menggunakan algoritma SHA256 enkode dengan format string hex.
user_data.address[].city	string	Kota untuk alamat pengguna. Dinormalkan seperti berikut: hapus digit dan karakter simbol huruf kecil hapus spasi di awal dan di akhir
user_data.address[].region	string	Negara bagian atau wilayah untuk alamat pengguna. Dinormalkan seperti berikut: hapus digit dan karakter simbol huruf kecil hapus spasi di awal dan di akhir
user_data.address[].postal_code	string	Kode pos untuk alamat pengguna. Dinormalkan seperti berikut: hapus karakter `.` dan `~` hapus spasi di awal dan di akhir
user_data.address[].country	string	Kode negara untuk alamat pengguna. Diformat menurut standar ISO 3166-1 alpha-2.

Lihat dokumentasi referensi Measurement Protocol untuk mengetahui informasi selengkapnya tentang cara pemformatan transportasi dan payload.

Mengirim Data yang Disediakan Pengguna

Tidak seperti gtag, yang secara otomatis melakukan hash pada data sensitif yang disediakan pengguna, Measurement Protocol mengharuskan developer untuk memberi hash pada data sensitif yang disediakan pengguna menggunakan algoritma hash satu arah yang aman yang disebut SHA256 dan mengenkodenya menggunakan format string hex sebelum memanggil API.

Semua kolom data pengguna yang dimulai dengan imbuhan sha256 di namanya hanya boleh diisi dengan nilai yang berenkode heksadesimal dan di-hash.

Kode contoh berikut melakukan langkah-langkah encoding dan enkripsi yang diperlukan:

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

Sebagai pintasan praktis, semua kolom berulang di dalam objek user_data (seperti address, sha256_email_address, sha256_phone_number) dapat diteruskan sebagai nilai tunggal, bukan array.

Kode contoh berikut memanggil Measurement Protocol dan meneruskan data pengguna bersama dengan 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
      }
    }
  })
});

Banyak nilai

Developer dapat memilih untuk memberikan banyak nilai (hingga 3 untuk telepon dan email, dan 2 untuk alamat) menggunakan nilai array, bukan string. Jika Anda mengambil lebih dari satu nilai, memberikan nilai ini akan meningkatkan kemungkinan kecocokan.

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