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

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

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

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

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

  • إزالة المسافات البيضاء البادئة واللاحقة
  • تحويل النص إلى أحرف لاتينية صغيرة
  • تنسيق أرقام الهواتف وفقًا E164 Standard:
  • إزالة جميع النقاط (.) التي تسبق اسم النطاق في 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
      }]
    }
  })
});