إرسال البيانات المقدَّمة من المستخدِم مع User-ID باستخدام Measurement Protocol

على غرار استخدام gtag، من الممكن استخدام Measurement Protocol في "إحصاءات Google" من أجل "إحصاءات Google 4" لإرسال البيانات المقدَّمة من المستخدِم مع User-ID، والتي يمكن استخدامها لتحسين السلوك وقياس الإحالات الناجحة.

لإرسال البيانات المقدَّمة من المستخدِم مع طلب Measurement Protocol، أضِف المَعلمة user_data في حمولة JSON. يجب أن تكون المَعلمة user_id متوفّرة عند توفير السمة user_data.

يستخدم Measurement Protocol خوارزمية التسوية والتجزئة نفسها التي تستخدمها ميزة القياس المحسّن في Google Ads API. ولضمان الخصوصية، يجب تجزئة عناوين البريد الإلكتروني وأرقام الهواتف والأسماء الأولى وأسماء العائلة وعناوين الشوارع باستخدام خوارزمية SHA-256 قبل تحميلها. يجب ترميز القيمة المجزّأة بتنسيق سلسلة سداسية عشرية (كائن سلسلة يحتوي على أرقام سداسية عشرية فقط)، مثل 88d7ecb5c5b21d7b1.

لتوحيد نتائج التجزئة، عليك تنفيذ ما يلي قبل تجزئة إحدى هذه القيم:

  • إزالة المسافات البيضاء البادئة واللاحقة
  • تحويل النص إلى أحرف لاتينية صغيرة
  • تنسيق أرقام الهواتف وفقًا لمعيار E164
  • إزالة جميع النقاط (.) التي تسبق اسم النطاق في gmail.com وgooglemail.com عنوان البريد الإلكتروني

نص مشاركة JSON

المفتاح النوع الوصف
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 من مطوّر البرامج تجزئة البيانات الحساسة المقدَّمة من المستخدم باستخدام خوارزمية تجزئة آمنة أحادية الاتجاه تُعرف باسم 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
      }]
    }
  })
});