تجمع ميزة "مطابقة البيانات المقدّمة من المستخدم" (UPDM) بين بيانات الطرف الأول التي جمعتها عن مستخدم معيّن، مثل المعلومات من مواقعك الإلكترونية أو تطبيقاتك أو متاجرك، ونشاط هذا المستخدم نفسه أثناء تسجيل الدخول إلى جميع بيانات إعلانات Google، بما في ذلك البيانات التي تملكها Google وتديرها. ويشمل ذلك البيانات التي يتم شراؤها من خلال منتجات "منصّة Google للتسويق" (GMP)، مثل YouTube الذي يتم شراؤه باستخدام "مساحة العرض والفيديو 360". لا تتوفّر منتجات GMP الأخرى التي لا تملكها Google ولا تديرها.
لتصبح مؤهَّلاً لمطابقة البيانات المقدَّمة من المستخدم، يجب ربط حدث الإعلان بالمستخدم الذي سجّل الدخول إلى البيانات في "إعلانات Google".
يوضّح هذا المستند ميزة مطابقة البيانات المقدَّمة من المستخدِم، ويقدّم إرشادات حول عملية الإعداد والاستخدام.
نظرة عامة على علامة التبويب "عمليات الربط"
يتطلّب الحصول على إحصاءات إعلانية قيّمة غالبًا تجميع البيانات من مصادر متعدّدة. يتطلّب إنشاء حلّ خاص بك لمشكلة مسار نقل البيانات هذا استثمارًا كبيرًا للوقت والجهد الهندسي. تسهّل صفحة "عمليات الربط" في Ads Data Hub هذه العملية من خلال توفير واجهة إرشادية خطوة بخطوة لاستيراد بيانات إعلاناتك وتحويلها ومطابقتها في BigQuery، ما يتيح لك استخدامها في طلبات البحث في Ads Data Hub أو أي منتج آخر يقرأ البيانات من BigQuery. يمكن أن يؤدي إثراء طلبات البحث ببيانات الطرف الأول إلى تقديم تجارب أفضل للعملاء، كما أنّه أكثر مقاومة للتغييرات على مستوى المجال في تتبُّع الإعلانات.
تم إنشاء صفحة "عمليات الربط" باستخدام أدوات تتيح لك تشفير معلومات تحديد الهوية الشخصية ومشاركتها مع الشركاء بطريقة تركّز على الخصوصية. بعد اختيار الأعمدة التي تحتوي على معلومات تحديد الهوية الشخصية، يشفّر Ads Data Hub البيانات، ما يضمن عدم إمكانية تصدير بيانات الطرف الأول أو قراءتها إلا من قِبل المستخدمين الذين لديهم إذن بذلك. قد يكون من الصعب معرفة بيانات الطرف الأول المطلوبة لحالة استخدام القياس أو التفعيل، لذا يقدّم Ads Data Hub قائمة شاملة بحالات الاستخدام المحدّدة مسبقًا، ثم يرشدك خلال تجربة استخراج بياناتك وتحويلها وتحميلها بالكامل. على الرغم من أنّه يمكنك إنشاء أنواع متعدّدة من عمليات الربط، يفترض هذا المستند أنّك تستخدم صفحة "عمليات الربط" لمطابقة البيانات المقدَّمة من المستخدِم.
مصادر بيانات الطرف الأول المتوافقة
يمكنك استيراد البيانات من مصادر البيانات التالية:
- BigQuery
- Cloud Storage
- بروتوكول نقل الملفات الآمن (SFTP)
- Snowflake
- MySQL
- PostgreSQL
- Amazon Redshift
- Amazon S3
بما أنّ ميزة "مطابقة البيانات المقدَّمة من المستخدِم" لا تتوفّر إلا في المستودع الذي تملكه وتديره Google للمستخدمين الذين سجّلوا الدخول، فإنّها لا تتأثر بالإيقاف النهائي القادم لملفات تعريف الارتباط التابعة لجهات خارجية. وبما أنّها أكثر قدرة على مقاومة التغيّرات في المجال مقارنةً بالبيانات التابعة لجهات خارجية، يمكنها تقديم إحصاءات أكثر تفصيلاً، ما قد يؤدي إلى زيادة تفاعل العملاء.
التعرُّف على المصطلحات
- ربط البيانات المقدَّمة من المستخدِم: يمكنك إعداد عملية ربط البيانات المقدَّمة من المستخدِم لاستيراد بياناتك ومطابقتها، وجدولة عمليات استيراد البيانات، وتحويل البيانات، ومطابقة بيانات إعلاناتك باستخدام رقم تعريف المستخدِم. يجب ربط حدث الإعلان بمستخدم سجّل الدخول إلى البيانات في "إعلانات Google". يتطلّب مشاريع متعددة على Google Cloud.
- ربط بيانات الطرف الأول: يمكنك إعداد عملية ربط بيانات الطرف الأول كأداة لإعداد البيانات، وذلك لجدولة عمليات استيراد البيانات وتحويلها بدون الميزات المتقدّمة في "إدارة بيانات المستخدمين". لا يتطلّب هذا النوع من الربط سوى مشروع واحد على Google Cloud.
- مصدر البيانات: منتج مرتبط أو ملف مستورَد أو عملية دمج مع منتج خارجي، مثل BigQuery.
- الوجهة: حالة استخدام، وهي عادةً عبارة عن منتج من Google أو ميزة في منتج، تم فيها تفعيل خاصية استيراد البيانات، مثل ميزة "مطابقة البيانات المقدَّمة من المستخدِم" في "مركز بيانات إعلانات Google".
- مشروع المشرف: مشروع Google Cloud الذي يحتوي على بياناتك الإعلانية الخاصة بتنسيقها الأوّلي.
- مجموعة بيانات الإخراج: هي مجموعة بيانات BigQuery التي يكتب إليها "مركز بيانات إعلانات Google". بشكل تلقائي، تكون هذه مجموعة بيانات ضمن مشروع المشرف. لتغييره إلى مشروع آخر على Google Cloud، يُرجى الاطّلاع على إعداد حسابات الخدمة.
ملخّص العملية
- إعداد عملية استيعاب البيانات ومطابقتها
- تمنح حسابات الخدمة الأذونات المطلوبة في مشروع المشرف. راجِع مقالة إعداد عملية استيعاب البيانات.
- نقل بيانات الطرف الأول ومطابقتها
- أنت تحدّد تنسيق بيانات الطرف الأول وتحمّلها إلى مجموعة بيانات BigQuery. لإجراء الإعدادات بأبسط طريقة، استخدِم مشروع المشرف. ومع ذلك، يمكنك استخدام أي مجموعة بيانات BigQuery تملكها.
- تبدأ بتقديم طلب مطابقة البيانات من خلال إنشاء عملية ربط وتحديد جدول زمني للاستيراد.
- تدمج Google البيانات بين مشروعك والبيانات المملوكة لشركة Google والتي تحتوي على معرّف المستخدم في Google والبيانات المجزّأة المقدَّمة من المستخدم لإنشاء جداول المطابقة وتعديلها.
- راجِع مقالة نقل بيانات الطرف الأول
- طلبات البحث المستمرة في Ads Data Hub، استنادًا إلى البيانات المطابَقة
- يمكنك تنفيذ طلبات بحث على جداول المطابقة بالطريقة نفسها التي تنفّذ بها طلبات البحث العادية في Ads Data Hub. يمكنك الاطّلاع على الاستعلام عن البيانات المطابقة.
التعرّف على متطلبات الخصوصية
جمع بيانات العملاء
عند استخدام ميزة "مطابقة البيانات المقدَّمة من المستخدم"، عليك تحميل بيانات الطرف الأول. ويمكن أن تكون هذه المعلومات هي المعلومات التي جمعتها من مواقعك الإلكترونية أو تطبيقاتك أو متاجرك أو أي معلومات شاركها معك أحد العملاء مباشرةً.
يجب تنفيذ ما يلي:
- التأكّد من أنّ سياسة الخصوصية لديك تكشف أنّك تشارك بيانات العملاء مع أطراف ثالثة لتقديم خدمات نيابةً عنك، وأنّك تحصل على موافقة لهذه المشاركة إذا كان ذلك مطلوبًا قانونًا
- استخدام واجهة برمجة تطبيقات (API) أو واجهة وافقت Google عليها فقط لتحميل بيانات العملاء
- الالتزام بكل القوانين واللوائح السارية، بما في ذلك أي قواعد ذاتية التنظيم أو قواعد متّبعة في المجال قد تنطبق
إقرار الموافقة من الطرف الأول
لضمان إمكانية استخدام بيانات الطرف الأول في Ads Data Hub، عليك تأكيد حصولك على الموافقة المناسبة لمشاركة البيانات مع Google من المستخدمين النهائيين في المنطقة الاقتصادية الأوروبية، وذلك بموجب سياسة موافقة المستخدم في الاتحاد الأوروبي وسياسة Ads Data Hub. ينطبق هذا الشرط على كل حساب على Ads Data Hub، ويجب تعديله في كل مرة تحمّل فيها بيانات جديدة خاصة بالطرف الأول. يمكن لأي مستخدم تقديم هذا الإقرار نيابةً عن الحساب بأكمله.
يُرجى العِلم أنّ قواعد طلبات البحث في خدمات Google نفسها التي تنطبق على طلبات البحث في التحليل تنطبق أيضًا على طلبات البحث في "إدارة خصوصية المستخدم". على سبيل المثال، لا يمكنك تنفيذ طلبات بحث على مستوى خدمات متعددة بشأن المستخدمين في المنطقة الاقتصادية الأوروبية عند إنشاء جدول مطابقة.
للتعرّف على كيفية إقرار الموافقة في Ads Data Hub، يُرجى الاطّلاع على متطلبات الموافقة في المنطقة الاقتصادية الأوروبية.
حجم البيانات
لحماية خصوصية المستخدمين النهائيين، تفرض ميزة "مطابقة البيانات المقدَّمة من المستخدم" المتطلبات التالية بشأن حجم بياناتك:
- يجب تحميل 1,000 سجلّ على الأقل في قائمة المستخدمين.
- يجب أن يتضمّن كل تعديل ناجح لجدول مطابقة المستخدمين الحدّ الأدنى من عدد المستخدمين الذين تمّت مطابقتهم حديثًا. يشبه هذا السلوك عمليات التحقّق من الاختلافات.
- يجب ألا تتجاوز قائمتك الحد الأقصى لعدد السجلات. لمعرفة الحد الأقصى لحجم البيانات، يُرجى التواصل مع ممثل Google.
إعداد عملية استيعاب البيانات
قبل البدء، عليك إعداد حسابك على Ads Data Hub لإنشاء عمليات ربط البيانات، وهي الطريقة التي ستنشئ بها مسار مطابقة البيانات. لن تحتاج إلى تنفيذ هذه الخطوات سوى مرة واحدة.
من صفحة عمليات الربط، انقر على بدء الإعداد لفتح معالج إعداد الحساب في مرحلة تفعيل "إدارة بيانات المستخدمين الموحّدة".
ما هي الأذونات الممنوحة لـ BigQuery وCloud Storage؟
في حال إعداد ميزة "مطابقة البيانات المقدَّمة من المستخدم" لاستخدامها مع BigQuery أو Cloud Storage، استخدِم هذا المرجع للتعرّف على الأذونات التي يتم منحها لحسابات خدمة Ads Data Hub.
BigQuery
حساب خدمة Datafusion | |||||||||
الغرض | يُستخدَم حساب خدمة Data Fusion لعرض قائمة بحقول المصادر في واجهة مستخدم Ads Data Hub. | ||||||||
التنسيق | service-some-number@gcp-sa-datafusion.iam.gserviceaccount.com |
||||||||
أذونات الوصول المطلوبة |
|
||||||||
حساب خدمة Dataproc | |||||||||
الغرض | يكون حساب خدمة Dataproc مسؤولاً عن تشغيل مسارات التعلّم الخاصة بالبيانات في الخلفية. | ||||||||
التنسيق | some-number-compute@developer.gserviceaccount.com |
||||||||
أذونات الوصول المطلوبة |
|
||||||||
حساب خدمة إدارة الأجهزة الجوّالة من Google | |||||||||
الغرض | يتم استخدام حساب خدمة UPDM لتشغيل مهمة المطابقة. | ||||||||
التنسيق | service-some-number@gcp-sa-adsdataconnector.iam.gserviceaccount.com |
||||||||
أذونات الوصول المطلوبة |
|
Cloud Storage
حساب خدمة Datafusion | |||||||
الغرض | يُستخدَم حساب خدمة Data Fusion لعرض قائمة بحقول المصادر في واجهة مستخدم Ads Data Hub. | ||||||
التنسيق | service-some-number@gcp-sa-datafusion.iam.gserviceaccount.com |
||||||
أذونات الوصول المطلوبة |
|
||||||
حساب خدمة Dataproc | |||||||
الغرض | يكون حساب خدمة Dataproc مسؤولاً عن تشغيل مسارات التعلّم الخاصة بالبيانات في الخلفية. | ||||||
التنسيق | some-number-compute@developer.gserviceaccount.com |
||||||
أذونات الوصول المطلوبة |
|
||||||
حساب خدمة إدارة الأجهزة الجوّالة من Google | |||||||
الغرض | يتم استخدام حساب خدمة UPDM لتشغيل مهمة المطابقة. | ||||||
التنسيق | service-some-number@gcp-sa-adsdataconnector.iam.gserviceaccount.com |
||||||
أذونات الوصول المطلوبة |
|
مصادر البيانات الأخرى
غير ضروري لمصادر البيانات الأخرى
استيعاب بيانات الطرف الأول ومطابقتها
تنسيق البيانات للإدخال
يجب أن تلتزم بياناتك بمتطلبات التنسيق التالية لتتم مطابقتها بشكل صحيح:
- يجب تحميل الملفات باستخدام تجزئة SHA256 في المواضع المحدّدة في أوصاف حقول الإدخال التالية.
- يجب تنسيق حقول الإدخال كسلاسل. على سبيل المثال، إذا كنت تستخدم دالة التجزئة SHA256 من BigQuery مع دالة الترميز Base16 (TO_HEX)، استخدِم عملية التحويل التالية:
TO_HEX(SHA256(user_data))
. - يتوافق UPDM مع ترميز Base16 وBase64. يجب أن تتوافق عملية ترميز بيانات الطرف الأول مع عملية فك الترميز المستخدَمة في طلب البحث على Ads Data Hub. في حال تغيير ترميز بيانات الطرف الأول، عليك تعديل طلب البحث في Ads Data Hub لفك الترميز من الأساس نفسه. تستخدِم الأمثلة التالية ترميز Base16.
رقم تعريف المستخدم
- نص عادي
- التجزئة: ما مِن تجزئة
البريد الإلكتروني
- إزالة المسافات البيضاء البادئة واللاحقة
- يجب أن تكون كل الأحرف صغيرة
- أدرِج اسم نطاق لجميع عناوين البريد الإلكتروني، مثل gmail.com أو hotmail.co.jp
- إزالة علامات التشكيل، مثلاً تغيير è أو é أو ê أو ë إلى e
- إزالة جميع النقاط (.) التي تسبق اسم النطاق في عناوين البريد الإلكتروني
gmail.com
وgooglemail.com
- التجزئة: خوارزمية SHA256 بترميز Base16
صالح: TO_HEX(SHA256("jeffersonloveshiking@gmail.com"))
غير صالح: TO_HEX(SHA256("JéffersonLôvesHiking@gmail.com"))
الهاتف
- إزالة المسافة البيضاء
- التنسيق بتنسيق E.164، على سبيل المثال، الولايات المتحدة: +14155552671، المملكة المتحدة: +442071838750
- إزالة جميع الرموز الخاصة باستثناء علامة "+" قبل رمز البلد
- التجزئة: خوارزمية SHA256 بترميز Base16
صالح: TO_HEX(SHA256("+18005550101"))
غير صالح: TO_HEX(SHA256("(800) 555-0101"))
الاسم الأول
- إزالة المسافة البيضاء
- يجب أن تكون كل الأحرف صغيرة
- إزالة جميع البادئات، مثل "السيدة" سيد Ms., الدكتور
- لا تُزِل علامات التشكيل، مثل è أو é أو ê أو ë
- التجزئة: خوارزمية SHA256 بترميز Base16
صالح: TO_HEX(SHA256("daní"))
غير صالح: TO_HEX(SHA256("Daní"))
اسم العائلة
- إزالة المسافة البيضاء
- يجب أن تكون كل الأحرف صغيرة
- إزالة جميع اللاحقات، مثل Jr. Sr., 2nd, 3rd, II, III, PHD, MD
- لا تُزِل علامات التشكيل، مثل è أو é أو ê أو ë
- التجزئة: خوارزمية SHA256 بترميز Base16
صالح: TO_HEX(SHA256("delacruz"))
غير صالح: TO_HEX(SHA256("de la Cruz, Jr."))
البلد
- أدرِج رمز البلد حتى إذا كانت كل بيانات العملاء واردة من البلد نفسه.
- يجب ألا تتم تجزئة بيانات البلد
- استخدام رموز البلدان وفقًا لمعيار ISO 3166-1 alpha-2
- التجزئة: ما مِن تجزئة
صالح: US
غير صالح: United States of America
أو USA
الرمز البريدي
- عدم تجزئة بيانات الرمز البريدي
- مسموح باستخدام الرموز البريدية الأمريكية والدولية
- في الولايات المتحدة:
- يُسمح باستخدام الرموز المكوّنة من 5 أرقام، مثل 94043
- يُسمح أيضًا باستخدام 5 أرقام متبوعة بإضافة مكوّنة من 4 أرقام، مثل 94043-1351 أو 940431351
- بالنسبة إلى جميع البلدان الأخرى:
- لا حاجة إلى التنسيق (لا حاجة إلى تحويل الأحرف إلى صغيرة أو إزالة المسافات والرموز الخاصة)
- استبعد إضافات الرموز البريدية
- التجزئة: ما مِن تجزئة
التحقّق من صحة التجزئة وترميز البيانات
يمكنك استخدام نصوص التحقّق من صحة التجزئة التالية للتأكّد من تنسيق بياناتك بشكلٍ صحيح.
JavaScript
Base16
/**
* @fileoverview Provides the hashing algorithm for User-Provided Data Match, as
* well as some valid hashes of sample data for testing.
*/
async function hash(token) {
// Removes leading or trailing spaces and converts all characters to lowercase.
const formattedToken = token.trim().toLowerCase();
// Hashes the formatted string using the SHA-256 hashing algorithm.
const hashArrayBuffer = await crypto.subtle.digest(
'SHA-256', (new TextEncoder()).encode(formattedToken));
// Converts the hash buffer to a hexadecimal string.
return Array.from(new Uint8Array(hashArrayBuffer))
.map((b) => b.toString(16).padStart(2, '0'))
.join('');
}
function main() {
// Expected hash for test@gmail.com:
// 87924606b4131a8aceeeae8868531fbb9712aaa07a5d3a756b26ce0f5d6ca674
hash('test@gmail.com').then(result => console.log(result));
// Expected hash for +18005551212:
// 61d9111bed3e6d9cfc1bc3b5cb35a402687c4f1546bee061a2bd444fbdd64c44
hash('+18005551212').then(result => console.log(result));
// Expected hash for John:
// 96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a
hash('John').then(result => console.log(result));
// Expected hash for Doe:
// 799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f
hash('Doe').then(result => console.log(result));
}
main()
Base64
/**
* @fileoverview Provides the hashing algorithm, as well as some valid hashes of
* sample data for testing.
*/
async function hash(token) {
// Removes leading or trailing spaces and converts all characters to lowercase.
const formattedToken = token.trim().toLowerCase();
// Hashes the formatted string using the SHA-256 hashing algorithm.
const hashBuffer = await crypto.subtle.digest(
'SHA-256', (new TextEncoder()).encode(formattedToken));
// Converts the hash buffer to a base64-encoded string and returns it.
const base64Str = btoa(String.fromCharCode(...new Uint8Array(hashBuffer)));
return base64Str;
}
function main() {
// Expected hash for test@gmail.com:
// h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
hash('test@gmail.com').then(result => console.log(result));
// Expected hash for +18005551212:
// YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
hash('+18005551212').then(result => console.log(result));
// Expected hash for John: ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
hash('John').then(result => console.log(result));
// Expected hash for Doe: eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
hash('Doe').then(result => console.log(result));
}
main()
Python
Base16
"""Provides the hashing algorithm, as well as some valid hashes of sample data for testing.
Supports: Python 2, Python 3
Sample hashes:
- Email 'test@gmail.com': 87924606b4131a8aceeeae8868531fbb9712aaa07a5d3a756b26ce0f5d6ca674
- Phone '+18005551212': 61d9111bed3e6d9cfc1bc3b5cb35a402687c4f1546bee061a2bd444fbdd64c44
- First name 'John': 96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a
- Last name 'Doe': 799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f
"""
import base64
import hashlib
def updm_hash(token):
# Generates a SHA-256 hash of the input token after normalization.
return hashlib.sha256(token.strip().lower().encode('utf-8')).hexdigest()
def print_updm_hash(token):
# Prints the SHA-256 hash and the original token.
print('Hash: "{}"\t(Token: {})'.format(updm_hash(token), token))
def main():
# Hashes and prints sample tokens.
print_updm_hash('test@gmail.com')
print_updm_hash('+18005551212')
print_updm_hash('John')
print_updm_hash('Doe')
if __name__ == '__main__':
main()
Base64
"""Provides the hashing algorithm, as well as some valid hashes of sample data for testing.
Supports: Python 2, Python 3
Sample hashes:
- Email 'test@gmail.com': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
- Phone '+18005551212': YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
- First name 'John': ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
- Last name 'Doe': eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
"""
import base64
import hashlib
def hash(token):
# Generates a base64-encoded SHA-256 hash of a normalized input string.
return base64.b64encode(
hashlib.sha256(
token.strip().lower().encode('utf-8')).digest()).decode('utf-8')
def print_hash(token, expected=None):
# Computes and displays the hash of a token, with optional validation.
hashed = hash(token)
if expected is not None and hashed != expected:
print(
'ERROR: Incorrect hash for token "{}". Expected "{}", got "{}"'.format(
token, expected, hashed))
return
print('Hash: "{}"\t(Token: {})'.format(hashed, token))
def main():
# Tests the hash function with sample tokens and expected results.
print_hash(
'test@gmail.com', expected='h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=')
print_hash(
'+18005551212', expected='YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=')
print_hash('John', expected='ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=')
print_hash('Doe', expected='eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=')
if __name__ == '__main__':
main()
Go
Base16
/*
Provides the hashing algorithm, as well as some valid hashes of sample data for testing.
Sample hashes:
- Email 'test@gmail.com': 87924606b4131a8aceeeae8868531fbb9712aaa07a5d3a756b26ce0f5d6ca674
- Phone '+18005551212': 61d9111bed3e6d9cfc1bc3b5cb35a402687c4f1546bee061a2bd444fbdd64c44
- First name 'John': 96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a
- Last name 'Doe': 799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f
*/
package main
import (
"crypto/sha256"
"fmt"
"strings"
)
// Hash hashes an email, phone, first name, or last name into the correct format.
func Hash(token string) string {
formatted := strings.TrimSpace(strings.ToLower(token))
hashed := sha256.Sum256([]byte(formatted))
encoded := fmt.Sprintf("%x", hashed[:])
return encoded
}
// PrintHash prints the hash for a token.
func PrintHash(token string) {
fmt.Printf("Hash: \"%s\"\t(Token: %s)\n", Hash(token), token)
}
func main() {
PrintHash("test@gmail.com")
PrintHash("+18005551212")
PrintHash("John")
PrintHash("Doe")
}
Base64
/*
Provides the hashing algorithm, as well as some valid hashes of sample data for testing.
Sample hashes:
- Email 'test@gmail.com': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
- Phone '+18005551212': YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
- First name 'John': ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
- Last name 'Doe': eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
*/
package main
import (
"crypto/sha256"
"encoding/base64"
"fmt"
"strings"
)
// Hash hashes an email, phone, first name, or last name into the correct format.
func Hash(token string) string {
formatted := strings.TrimSpace(strings.ToLower(token))
hashed := sha256.Sum256([]byte(formatted))
encoded := base64.StdEncoding.EncodeToString(hashed[:])
return encoded
}
// PrintHash prints the hash for a token.
func PrintHash(token string) {
fmt.Printf("Hash: \"%s\"\t(Token: %s)\n", Hash(token), token)
}
func main() {
PrintHash("test@gmail.com")
PrintHash("+18005551212")
PrintHash("John")
PrintHash("Doe")
}
Java
Base16
package updm.hashing;
import static java.nio.charset.StandardCharsets.UTF_8;
import com.google.common.base.Ascii;
import com.google.common.hash.Hashing;
/**
* Example of the UPDM hashing algorithm using hex-encoded SHA-256.
*
* <p>This uses the Guava Hashing to generate the hash: https://github.com/google/guava
*
* <p>Sample valid hashes:
*
* <ul>
* <li>Email "test@gmail.com": "87924606b4131a8aceeeae8868531fbb9712aaa07a5d3a756b26ce0f5d6ca674"
* <li>Phone "+18005551212": "61d9111bed3e6d9cfc1bc3b5cb35a402687c4f1546bee061a2bd444fbdd64c44"
* <li>First name "John": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a"
* <li>Last name "Doe": "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f"
* </ul>
*/
public final class HashExample {
private HashExample() {}
public static String hash(String token) {
// Normalizes and hashes the input token.
String formattedToken = Ascii.toLowerCase(token).strip();
return Hashing.sha256().hashString(formattedToken, UTF_8).toString();
}
public static void printHash(String token) {
// Calculates and prints the token's hash.
System.out.printf("Hash: \"%s\"\t(Token: %s)\n", hash(token), token);
}
public static void main(String[] args) {
// Executes hash calculations and prints results for sample tokens.
printHash("test@gmail.com");
printHash("+18005551212");
printHash("John");
printHash("Doe");
}
}
Base64
package updm.hashing;
import static java.nio.charset.StandardCharsets.UTF_8;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
/**
* Example of the hashing algorithm.
*
* <p>Sample hashes:
*
* <ul>
* <li>Email 'test@gmail.com': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
* <li>Phone '+18005551212': YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
* <li>First name 'John': ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
* <li>Last name 'Doe': eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
* </ul>
*/
public final class HashExample {
private HashExample() {}
public static String hash(String token) {
// Normalizes and hashes the input token using SHA-256 and Base64 encoding.
String formattedToken = token.toLowerCase().strip();
byte[] hash;
try {
hash = MessageDigest.getInstance("SHA-256").digest(formattedToken.getBytes(UTF_8));
} catch (NoSuchAlgorithmException e) {
throw new IllegalStateException("SHA-256 not supported", e);
}
return Base64.getEncoder().encodeToString(hash);
}
public static void printHash(String token) {
// Calculates and prints the hash for the given token.
System.out.printf("Hash: \"%s\"\t(Token: %s)\n", hash(token), token);
}
public static void main(String[] args) {
// Executes hash calculations and prints results for sample tokens.
printHash("test@gmail.com");
printHash("+18005551212");
printHash("John");
printHash("Doe");
}
}
SQL
Base16
/*
Provides the hashing algorithm, as well as some valid hashes of sample data for testing.
The following code uses Google Standard SQL and can be run on BigQuery to generate match tables from unhashed data.
Sample hashes:
- Email 'test@gmail.com': 87924606b4131a8aceeeae8868531fbb9712aaa07a5d3a756b26ce0f5d6ca674
- Phone '+18005551212': 61d9111bed3e6d9cfc1bc3b5cb35a402687c4f1546bee061a2bd444fbdd64c44
- First name 'John': 96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a
- Last name 'Doe': 799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f
The unhashed input table schema is assumed to be:
- Column name: UserID, Type: String
- Column name: Email, Type: String
- Column name: Phone, Type: String
- Column name: FirstName, Type: String
- Column name: LastName, Type: String
- Column name: PostalCode, Type: String
- Column name: CountryCode, Type: String
*/
-- Creates a new table with hashed versions of specified columns from the input table.
CREATE TABLE `your_project_name.your_dataset_name.output_hashed_table_name`
AS
SELECT
UserID,
TO_HEX(SHA256(LOWER(Email))) AS Email,
TO_HEX(SHA256(Phone)) AS Phone,
TO_HEX(SHA256(LOWER(FirstName))) AS FirstName,
TO_HEX(SHA256(LOWER(LastName))) AS LastName,
PostalCode,
CountryCode,
FROM
`your_project_name.your_dataset_name.input_unhashed_table_name`;
Base64
/*
Provides the hashing algorithm, as well as some valid hashes of sample data for testing.
The following code uses Google Standard SQL and can be run on BigQuery to generate match tables from unhashed data.
Sample hashes:
- Email 'test@gmail.com': h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=
- Phone '+18005551212': YdkRG+0+bZz8G8O1yzWkAmh8TxVGvuBhor1ET73WTEQ=
- First name 'John': ltljLzY1ZMwwMlIUCc8iqFLyAy7sCZ7VlnwNAAzsYHo=
- Last name 'Doe': eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=
The unhashed input table schema is assumed to be:
- Column name: UserID, Type: String
- Column name: Email, Type: String
- Column name: Phone, Type: String
- Column name: FirstName, Type: String
- Column name: LastName, Type: String
- Column name: PostalCode, Type: String
- Column name: CountryCode, Type: String
*/
-- Creates a new table with Base64-encoded SHA-256 hashes of specified columns.
CREATE TABLE `your_project_name.your_dataset_name.output_hashed_table_name`
AS
SELECT
UserID,
TO_BASE64(SHA256(LOWER(Email))) AS Email,
TO_BASE64(SHA256(Phone)) AS Phone,
TO_BASE64(SHA256(LOWER(FirstName))) AS FirstName,
TO_BASE64(SHA256(LOWER(LastName))) AS LastName,
PostalCode,
CountryCode,
FROM
`your_project_name.your_dataset_name.input_unhashed_table_name`;
مفاتيح الدمج
بعض مجموعات البيانات المقدَّمة من المستخدم تكون أقوى من غيرها. في ما يلي قائمة بمجموعات مختلفة من البيانات المقدَّمة من المستخدم، مرتّبة حسب القوة النسبية. إذا كنت تستخدم عنوانًا، يجب تضمين: الاسم الأول واسم العائلة والبلد والرمز البريدي.
- البريد الإلكتروني أو رقم الهاتف أو العنوان (الأكثر صلة)
- رقم الهاتف والعنوان
- البريد الإلكتروني والعنوان
- البريد الإلكتروني، الهاتف
- العنوان
- الهاتف
- البريد الإلكتروني (الأضعف)
إنشاء جدول مطابقة
- انقر على عمليات الربط > إنشاء عملية ربط > مطابقة البيانات المقدَّمة من المستخدِم.
- اختَر مصدر بيانات، ثم انقر على ربط.
- أثبِت هويتك إذا طُلب منك ذلك، ثم انقر على التالي:
BigQuery
انقر على "تطبيق" لمنح إذن الوصول إلى BigQuery.
Cloud Storage
انقر على "تطبيق" لمنح إذن الوصول إلى Cloud Storage.
MySQL
أدخِل موقع قاعدة بيانات MySQL والمنفذ واسم المستخدم وكلمة المرور.
S3
أدخِل مفتاح الوصول السري الخاص بخدمة Amazon S3.
PostgreSQL
أدخِل موقع قاعدة بيانات PostgreSQL والمنفذ واسم المستخدم وكلمة المرور وقاعدة البيانات.
Redshift
أدخِل موقع قاعدة بيانات Redshift والمنفذ واسم المستخدم وكلمة المرور وقاعدة البيانات.
بروتوكول النقل الآمن للملفات (SFTP)
أدخِل موقع خادم بروتوكول النقل الآمن للملفات (SFTP) واسم المستخدم وكلمة المرور.
Snowflake
أدخِل معرّف حسابك واسم المستخدم وكلمة المرور على Snowflake.
- اضبط مصدر البيانات، ثم انقر على التالي:
BigQuery
اختَر جدول BigQuery الذي تريد استيراده.
Cloud Storage
أدخِل مسار gsutil، مثل
gs://my-bucket/folder/
، واختَر تنسيق ملفك.إذا كانت هذه هي المرة الأولى التي تربط فيها هذا المرجع، سيظهر تنبيه. انقر على "تطبيق" لمنح إذن الوصول، ثم انقر على "التالي". ملاحظة: يجب أن يكون لديك دور يملك الإذن بتفويض
storage.buckets.setIamPolicy
للحزمة ذات الصلة.MySQL
اختَر الجدول وقاعدة بيانات MySQL اللذين تريد استخدامهما.
S3
أدخِل معرِّف الموارد المنتظم (URI) الخاص بالملف الذي تريد تحميله، وفقًا لعنوان المضيف.
PostgreSQL
أدخِل اسم مخطط وجدول (أو طريقة عرض) PostgreSQL.
Redshift
أدخِل اسم مخطط وجدول (أو طريقة عرض) Redshift. بشكلٍ تلقائي، يستخدم Redshift عناوين URL الخاصة بالمواقع الجغرافية لقاعدة البيانات التي تتبع هذا النموذج:
cluster-identifier.account-number.aws-region.redshift.amazonaws.com
.بروتوكول النقل الآمن للملفات (SFTP)
أدخِل مسار الملف واسمه بالتنسيق التالي:
/PATH/FILENAME.csv
Snowflake
أدخِل قاعدة بيانات Snowflake والمخطّط والجدول (أو طريقة العرض) التي تريد استخدامها.
- اختَر مجموعة بيانات في BigQuery لاستخدامها كـ وجهة وسيطة، ثم انقر على التالي. تضمن هذه الخطوة تنسيق بياناتك بشكل صحيح.
- اختياري: عدِّل تنسيق بياناتك. تشمل عمليات التحويل احتساب التجزئة وتنسيق الأحرف الصغيرة/الكبيرة ودمج الحقول أو تقسيمها.
- انقر على الإجراء > > تحويل.
- في اللوحة التي تظهر، انقر على إضافة عملية تحويل أو إضافة عملية تحويل أخرى.
- اختَر نوع التحويل من القائمة المنسدلة وأدخِل المتطلبات.
- انقر على حفظ.
- اختَر مفتاح ربط واحدًا على الأقل واربط الحقول التي ستستخدمها. ستعمل خدمة Ads Data Hub تلقائيًا على ربط الحقول التي تحمل الأسماء نفسها، ويتم الإشارة إلى ذلك من خلال الرمز . أدخِل أي تعديلات ضرورية، ثم انقر على التالي.
- ضبط جدول زمني:
- أدخِل اسمًا لعملية الربط.
- اضبط فترة تكرار تحدّد عدد المرات التي سيتم فيها استيراد البيانات إلى مجموعة البيانات التي اخترتها في الخطوة السابقة. سيؤدي كل تشغيل إلى استبدال البيانات في جدول الوجهة.
- حدِّد الطريقة التي تريد بها التعامل مع حالات تعارض أرقام تعريف المستخدمين. يمكنك الاختيار بين الاحتفاظ بالمطابقة الحالية أو الكتابة فوقها ببيانات جديدة.
- انقر على إنهاء. تكون جداول المطابقة جاهزة بشكل عام للاستعلام بعد 12 ساعة من إنشائها.
عرض تفاصيل الربط
تقدّم لك صفحة تفاصيل عملية الربط معلومات عن عمليات التنفيذ والأخطاء الحديثة لعملية ربط معيّنة. للاطّلاع على تفاصيل اتصال معيّن، اتّبِع الخطوات التالية:
- انقر على عمليات الربط.
- انقر على اسم الاتصال لعرض تفاصيله.
- يمكنك الآن الاطّلاع على تفاصيل عملية الربط وعمليات التشغيل الأخيرة. يعرض كل منهما نوعَين محتملَين من الأخطاء: أخطاء على مستوى الاتصال (لم يتم تشغيل الاتصال) وأخطاء على مستوى الصف (لم يتم استيراد صف).
- تشير الحالة تعذّر إلى تعذّر تشغيل عملية الربط بالكامل (على سبيل المثال، مشكلة في أذونات حساب الخدمة). انقر على حالة الخطأ لمعرفة الأخطاء التي أثّرت في عملية الربط.
- تشير الحالة مكتملة إلى أنّ عملية الربط قد تمّت بنجاح. ومع ذلك، قد تظل هناك أخطاء على مستوى الصف، ويشير إلى ذلك قيمة غير صفرية في العمود "الصفوف التي تحتوي على أخطاء". انقر على القيمة لمعرفة المزيد من المعلومات حول السجلات التي تعذّر تحميلها.
تعديل عملية ربط
يمكن تعديل التفاصيل التالية:
- اسم عملية الربط
- الجدولة
- جدول الوجهة
- ربط الحقول
لا يمكن تعديل مصدر البيانات. لتغيير مصدر بيانات، أنشئ عملية ربط جديدة واحذف العملية القديمة.
لتعديل تفاصيل عملية الربط، اتّبِع الخطوات التالية:
- انقر على عمليات الربط.
- انقر على اسم عملية الربط التي تريد تعديلها.
- عدِّل التفاصيل التي تريد تغييرها:
- اسم الاتصال: انقر على تعديل، وأدخِل الاسم الجديد، ثم اضغط على Enter.
- الجدول الزمني: انقر على تعديل، واضبط الجدول الزمني الجديد، ثم انقر على حفظ.
- جدول الوجهة: انقر على تعديل، وأدخِل اسم الوجهة الجديد، ثم انقر على حفظ.
- ربط الحقول: انقر على ، وأدخِل التغييرات على الحقول، ثم انقر على حفظ.
- انقر على .
البيانات المطابِقة لطلب البحث
طلب البحث في جداول المطابقة
عندما تحتوي جداول المطابقة على بيانات كافية لاستيفاء عمليات التحقّق من الخصوصية، تكون مستعدًا لتنفيذ طلبات بحث على الجداول.
يتم تمثيل الجدول الأصلي لبيانات الطرف الأول (1PD) بالرمز my_data
.
ويشمل ذلك كلاً من معلومات تحديد الهوية الشخصية والبيانات غير المرتبطة بتحديد الهوية الشخصية.
يمكن أن يؤدي استخدام الجدول الأصلي إلى تحسين تقاريرك من خلال تقديم المزيد من الإحصاءات، لأنّه يمثّل جميع بيانات الطرف الأول التي تندرج ضمن النطاق، وذلك مقارنةً بجدول المطابقة.
يتم إرفاق جدول مطابقة بكل جدول في مخطط Ads Data Hub يحتوي على الحقل user_id
. على سبيل المثال، بالنسبة إلى جدول
adh.google_ads_impressions
، ينشئ Ads Data Hub أيضًا جدول مطابقة
يُسمى adh.google_ads_impressions_updm
يحتوي على أرقام تعريف المستخدمين.
يتم إنشاء جداول مطابقة منفصلة لجداول الشبكة المعزولة بالسياسة. على سبيل المثال، بالنسبة إلى الجدول adh.google_ads_impressions_policy_isolated_network
، ينشئ Ads Data Hub أيضًا جدول مطابقة باسم adh.google_ads_impressions_policy_isolated_network_updm
يحتوي على أرقام تعريف المستخدمين.
تحتوي هذه الجداول على مجموعة فرعية من المستخدمين المتاحين في الجداول الأصلية، حيث تتطابق قيمة user_id
. على سبيل المثال، إذا كان الجدول الأصلي يحتوي على بيانات للمستخدم (أ) والمستخدم (ب)، ولكن تمت مطابقة المستخدم (أ) فقط، لن يظهر المستخدم (ب) في جدول المطابقة.
تحتوي جداول المطابقة على عمود إضافي باسم customer_data_user_id
،
يخزّن معرّف المستخدِم كبايتات.
من المهم مراعاة نوع الحقل عند كتابة طلبات البحث. تتوقّع عوامل تشغيل المقارنة في SQL أن تكون القيم الحرفية التي تتم مقارنتها من النوع نفسه. استنادًا إلى طريقة تخزين user_id
في جدول بيانات الطرف الأول، قد تحتاج إلى ترميز القيم في الجدول قبل مطابقة البيانات.
يجب تحويل مفتاح الربط إلى BYTES للحصول على مطابقات ناجحة:
JOIN ON
adh.google_ads_impressions_updm.customer_data_user_id = CAST(my_data.user_id AS BYTES)
بالإضافة إلى ذلك، تكون مقارنات السلاسل في SQL حساسة لحالة الأحرف، لذا قد تحتاج إلى ترميز السلاسل على كلا جانبي المقارنة لضمان إمكانية مقارنتها بدقة.
نماذج طلبات البحث
عدد المستخدمين المطابقين
يحسب طلب البحث هذا عدد المستخدمين المطابِقين في جدول مرّات الظهور على "إعلانات Google".
/* Count matched users in Google Ads impressions table */
SELECT COUNT(DISTINCT user_id)
FROM adh.google_ads_impressions_updm
حساب نسبة المطابقة
لا يكون جميع المستخدمين مؤهّلين للمطابقة. على سبيل المثال، لا تتم مطابقة المستخدمين الذين سجّلوا الخروج والأطفال والمستخدمين الذين لم يوافقوا على استخدام UPDM. يمكنك استخدام الحقل is_updm_eligible
لحساب معدّلات تطابق أكثر دقة في "إدارة بيانات المستخدمين". يُرجى العِلم أنّ الحقل is_updm_eligible
كان متاحًا اعتبارًا من 1 أكتوبر 2024. ولا يمكنك استخدام هذا الحقل لحساب معدّلات المطابقة قبل هذا التاريخ.
/* Calculate the UPDM match rate */
CREATE TEMP TABLE total_events OPTIONS(privacy_checked_export=TRUE) AS
SELECT
customer_id,
COUNT(*) AS n
FROM adh.google_ads_impressions
WHERE is_updm_eligible
GROUP BY 1;
CREATE TEMP TABLE matched_events OPTIONS(privacy_checked_export=TRUE) AS
SELECT
customer_id,
COUNT(*) AS n
FROM adh.google_ads_impressions_updm
GROUP BY 1;
SELECT
customer_id,
SAFE_DIVIDE(matched_events.n, total_events.n) AS match_rate
FROM total_events
LEFT JOIN matched_events
USING (customer_id)
دمج بيانات الطرف الأول وبيانات "إعلانات Google"
يوضّح طلب البحث هذا كيفية دمج بيانات الطرف الأول مع بيانات "إعلانات Google":
/* Join first-party data with Google Ads data. The customer_data_user_id field
contains your ID as BYTES. You need to cast your join key into BYTES for
successful matches. */
SELECT
inventory_type,
COUNT(*) AS impressions
FROM
adh.yt_reserve_impressions_updm AS google_data_imp
LEFT JOIN
`my_data`
ON
google_data_imp.customer_data_user_id = CAST(my_data.user_id AS BYTES)
GROUP BY
inventory_type
الأسئلة الشائعة حول UPDM
للاطّلاع على قائمة بالأسئلة الشائعة ذات الصلة بمطابقة البيانات المقدَّمة من المستخدم، يُرجى الانتقال إلى الأسئلة الشائعة حول مطابقة البيانات المقدَّمة من المستخدم.