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

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

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

يستخدم Measurement Protocol قواعد التسوية والتجزئة نفسها التي تستخدمها Data Manager API والإحالات الناجحة المحسّنة في "إعلانات Google". لتجنّب أيّ مخاوف متعلّقة بالخصوصية، يجب تجزئة عناوين البريد الإلكتروني وأرقام الهواتف والأسماء الأولى وأسماء العائلة وعناوين الشوارع باستخدام خوارزمية 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.

اطّلِع على المستندات المرجعية لبروتوكول القياس لمزيد من المعلومات عن كيفية تنسيق النقل والحمولة.

إرسال البيانات المقدَّمة من المستخدم

على عكس 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
      }]
    }
  })
});