إرسال البيانات المقدَّمة من المستخدم عبر 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.

من أجل توحيد نتائج التجزئة، يجب إجراء ما يلي قبل تجزئة إحدى هذه القيم:

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

نص طلب POST بتنسيق 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 valueUtf8 = encoder.encode(value);
  // Compute the hash (digest) using the SHA-256 algorithm.
  const hashSha256 = await subtle.digest('SHA-256', valueUtf8);
  // Convert buffer to byte array.
  const hashArray = Array.from(new Uint8Array(hashSha256));
  // Return a hex-encoded string.
  return hashArray.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 measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

// 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=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    client_id: "CLIENT_ID",
    user_id: "USER_ID",
    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 measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    client_id: "CLIENT_ID",
    user_id: "USER_ID",
    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
      }]
    }
  })
});