داده های ارائه شده توسط کاربر را با User-ID با استفاده از پروتکل اندازه گیری ارسال کنید

مشابه استفاده از gtag ، می توان از پروتکل اندازه گیری Google Analytics برای Google Analytics 4 برای ارسال داده های ارائه شده توسط کاربر به همراه User-ID استفاده کرد که می تواند برای بهبود رفتار و اندازه گیری تبدیل استفاده شود.

برای ارسال داده‌های ارائه‌شده توسط کاربر به همراه درخواست پروتکل اندازه‌گیری، پارامتر user_data را در بار JSON اضافه کنید. هر زمان که user_data ارائه می شود، پارامتر user_id باید وجود داشته باشد.

پروتکل اندازه گیری از همان الگوریتم عادی سازی و هش کردن ویژگی اندازه گیری پیشرفته API Google Ads استفاده می کند. برای نگرانی‌های مربوط به حریم خصوصی، آدرس‌های ایمیل، شماره تلفن، نام، نام خانوادگی و نشانی خیابان باید با استفاده از الگوریتم SHA-256 قبل از آپلود هش شوند. مقدار هش شده باید در قالب رشته هگزا کدگذاری شود (شئ رشته حاوی فقط ارقام هگزا دسیمال) مانند 88d7ecb5c5b21d7b1 .

برای استاندارد کردن نتایج هش، قبل از هش کردن یکی از این مقادیر باید:

  • فضاهای سفید پیشرو و انتهایی را حذف کنید.
  • متن را به حروف کوچک تبدیل کنید.
  • فرمت شماره تلفن ها بر اساس استاندارد E164 .
  • تمام نقاط (.) که قبل از نام دامنه در آدرس های ایمیل gmail.com و googlemail.com قرار دارند را حذف کنید.

بدنه پست JSON

کلید تایپ کنید شرح
شناسه کاربر رشته یک شناسه منحصر به فرد برای یک کاربر. برای اطلاعات بیشتر در مورد این شناسه ، User-ID را برای تجزیه و تحلیل بین پلتفرمی ببینید.
کاربر_داده هدف - شی فیلدهای داده های کاربر پیشرفته که یک کاربر را شناسایی می کند.
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 آلفا-2 فرمت شده است.

برای اطلاعات بیشتر در مورد نحوه قالب بندی حمل و نقل و محموله، به مستندات مرجع پروتکل اندازه گیری مراجعه کنید.

ارسال داده های ارائه شده توسط کاربر

برخلاف gtag که به‌طور خودکار داده‌های حساس ارائه‌شده توسط کاربر را هش می‌کند، پروتکل اندازه‌گیری از یک توسعه‌دهنده می‌خواهد تا داده‌های حساس ارائه‌شده توسط کاربر را با استفاده از یک الگوریتم هش یک‌طرفه ایمن به نام 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
      }]
    }
  })
});