على غرار استخدام علامة gtag، يمكن استخدام بروتوكول Measurement Protocol في "إحصاءات Google" لإرسال البيانات المقدَّمة من المستخدِم مع User-ID، ما قد يتيح استخدامها لتحسين قياس الإحالات الناجحة والسلوك.
لإرسال البيانات المقدَّمة من المستخدِم مع طلب Measurement Protocol، أضِف المَعلمة
user_data في حمولة JSON. ننصحك أيضًا بتضمين المَعلمة user_id كلّما تم توفير user_data. يساعد ذلك في ضمان
أدق قياس وأداء للميزات.
يستخدم Measurement Protocol خوارزمية التجزئة والتسوية نفسها التي تستخدمها ميزة القياس المحسّن في Google Ads API.
للحيلولة دون أي مخاوف متعلقة بالخصوصية، يجب تجزئة عناوين البريد الإلكتروني وأرقام الهواتف والأسماء الأولى وأسماء العائلة وعناوين الشوارع باستخدام خوارزمية SHA-256 قبل تحميلها. يجب ترميز القيمة المجزأة بتنسيق سلسلة سداسية عشرية (كائن سلسلة
يحتوي على أرقام سداسية عشرية فقط)، مثل88d7ecb5c5b21d7b1.
لتوحيد نتائج التجزئة، عليك إجراء ما يلي قبل تجزئة إحدى هذه القيم:
- إزالة المسافات البيضاء البادئة واللاحقة
- تحويل النص إلى أحرف لاتينية صغيرة
- تنسيق أرقام الهواتف وفقًا لمعيار E164
- إزالة جميع النقاط (.) التي تسبق اسم النطاق في عناوين البريد الإلكتروني
gmail.comوgooglemail.com
نص طلب POST بتنسيق 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 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",
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",
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
}]
}
})
});