على غرار استخدام 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[] | صفيف السلاسل النصية | رقم هاتف المستخدِم المجزّأ والمشفّر
تمت تسويتها على هذا النحو:
|
user_data.address[] | صفيف | تحدِّد هوية المستخدم استنادًا إلى الموقع الجغرافي الفعلي. |
user_data.address[].sha256_first_name | سلسلة | الاسم الأول المجزّأ والمشفّر للمستخدِم.
تمت تسويتها على هذا النحو:
|
user_data.address[].sha256_last_name | سلسلة | اسم العائلة المجزّأ والمشفّر للمستخدم.
تمت تسويتها على هذا النحو:
|
user_data.address[].sha256_street | سلسلة | الشارع المجزّأ والمشفّر ورقم المستخدِم
تمت تسويتها على هذا النحو:
|
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
}]
}
})
});