تجمع ميزة "مطابقة البيانات المقدّمة من المستخدم" (UPDM) بين بيانات الطرف الأول التي جمعتها عن مستخدم معيّن، مثل المعلومات من مواقعك الإلكترونية أو تطبيقاتك أو متاجرك، ونشاط هذا المستخدم نفسه أثناء تسجيل الدخول إلى جميع بيانات الأداء مع إعلانات Google، بما في ذلك البيانات المملوكة وتحت إدارة Google. ويشمل ذلك البيانات التي يتم شراؤها من خلال منتجات "منصة Google للتسويق"، مثل YouTube الذي يتم شراؤه باستخدام "مساحة العرض والفيديو 360". لا تتوفّر منتجات "منصة Google للتسويق" الأخرى التي لا تملكها Google وتديرها.
لتصبح مؤهَّلاً لمطابقة البيانات المقدَّمة من المستخدم، يجب ربط حدث الإعلان بالمستخدم الذي سجّل الدخول إلى البيانات في "إعلانات Google".
يصف هذا المستند ميزة مطابقة البيانات المقدَّمة من المستخدم، ويقدّم إرشادات حول الإعداد والاستخدام.
نظرة عامة على Private Cloud Match
يتطلب الحصول على إحصاءات إعلانية قيّمة في كثير من الأحيان تجميع البيانات من مصادر متعددة. يتطلّب إنشاء حلّ خاص بك لمشكلة مسار البيانات هذه استثمارًا كبيرًا للوقت والجهد الهندسي. تعمل ميزة Private Cloud Match في Ads Data Hub على تبسيط هذه العملية من خلال توفير نموذج طلب بحث في Ads Data Hub لإنشاء جدول مطابقة في BigQuery يمكن استخدامه بعد ذلك في طلبات البحث في Ads Data Hub لمطابقة بيانات الأداء مع إعلاناتك مع بيانات الطرف الأول. يمكن أن يؤدي تحسين طلبات البحث باستخدام بيانات الطرف الأول إلى تقديم تجارب مستخدم أكثر ثراءً، كما أنّه أكثر مقاومة للتغييرات في تتبُّع الإعلانات على مستوى المجال.
بما أنّ ميزة "مطابقة البيانات المقدَّمة من المستخدم" لا تتوفّر إلا في المستودع الذي تملكه وتديره Google للمستخدمين الذين سجّلوا الدخول، فهي لا تتأثر بالإيقاف النهائي القادم لملفات تعريف الارتباط الخارجية. بما أنّها أكثر قدرة على مقاومة التغيرات في المجال مقارنةً بالبيانات التابعة لجهات خارجية، يمكنها تقديم إحصاءات أكثر تفصيلاً، ما يؤدي إلى زيادة تفاعل العملاء.
ملخّص العملية
- إعداد عملية نقل البيانات ومطابقتها
- أنت تأكَّد من أنّ بيانات الطرف الأول موجودة في 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 سجلّ على الأقل في قائمة المستخدمين.
إعداد عملية نقل البيانات
قبل البدء، تأكَّد مما يلي:
- يجب أن تكون بيانات الطرف الأول في BigQuery. إذا كان لديك محيط VPC-SC، يجب أن تكون بيانات الطرف الأول هذه ضمن محيط VPC-SC.
- يجب أن يكون لدى حساب خدمة Ads Data Hub إذن قراءة بيانات الطرف الأول.
- يجب تنسيق بيانات الطرف الأول وتجزئتها بشكلٍ صحيح. لمزيد من التفاصيل، انتقِل إلى الفقرة التالية.
وبخلاف ذلك، لا تتطلّب ميزة Private Cloud Match أي عملية إعداد إضافية. إذا كان بإمكانك تنفيذ طلب بحث تحليلي، يمكنك تنفيذ طلب بحث في Private Cloud Match.
استيراد بيانات الطرف الأول ومطابقتها
أذونات المصدر ومتطلبات الاتصال
تستخدم "عمليات الربط في Ads Data Hub" حساب الخدمة المعروض ضمن الإعدادات >
التفاصيل > حساب الخدمة (عادةً
service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com). امنحه هذه
الأدوار:
- مصدر BigQuery:
roles/bigquery.dataViewer(عارِض بيانات في BigQuery) في مجموعة البيانات أو الجدول المصدر - مصدر Cloud Storage:
roles/storage.objectViewer(Storage Object Viewer) في حزمة المصدر أو العنصر - وجهة استيراد بيانات الطرف الأول:
roles/bigquery.dataEditor(محرِّر بيانات BigQuery) في مجموعة البيانات المقصودة، إذا لم يكن الجدول ضمن مجموعة البيانات التلقائية
متطلبات الحقول وأنواع البيانات
تنطبق هذه القواعد على عمليات الربط في تجربة "الربط" المعدَّلة. وتعتمد على نوع الربط: مطابقة البيانات المقدَّمة من المستخدم أو بيانات الطرف الأول.
مطابقة البيانات المقدَّمة من المستخدم (UPDM)
يجب ربط user_id وسمة واحدة على الأقل من السمات التالية: email أو phone أو عنوان كامل (first_name وlast_name وcountry وzip_code). إذا ربطت أي عمود عنوان، يجب ربط الأعمدة الأربعة كلها. وإلا، لن تتمكّن من حفظ عملية الربط. لا يمكنك تغيير نوع هذه الأعمدة: فهو HASH لكل من email وphone وfirst_name وlast_name، وSTRING لكل من user_id وcountry وzip_code.
يجب أن يحتوي عمود المصدر الذي تربطه بكل عمود وجهة على ما يلي. لتنسيق القيم، يُرجى الاطّلاع على تنسيق البيانات للإدخال.
| عمود الوجهة | قيمة عمود المصدر | مثال |
|---|---|---|
user_id |
رقم تعريف المستخدم بتنسيق نص عادي | customer-1234 |
email، وphone، وfirst_name، وlast_name |
القيمة المنسَّقة، والمجزّأة باستخدام خوارزمية SHA-256، والمُرمَّزة بتنسيق Base64 (44 حرفًا). يمكن أيضًا استخدام ترميز Hex (64 حرفًا). | h5JGBrQTGorO7q6IaFMfu5cSqqB6XTp1aybOD11spnQ=، تجزئة test@gmail.com |
country |
رمز بلد مكوّن من حرفَين (ISO 3166-1 alpha-2)، بنص عادي | US |
zip_code |
رمز بريدي يتألف من 20 حرفًا كحدّ أقصى (الأحرف من A إلى Z والأرقام والمسافات والواصلات)، بنص عادي | 94043 |
- تجزئة القيم في المصدر: لا تُجري Connections تجزئة لـ
emailأوphoneأوfirst_nameأوlast_name، على الرغم من أنّ نوعها هو HASH. هناك استثناء واحد: إذا تم نقل عملية الربط إلى تجربة "عمليات الربط" المعدَّلة، وكان أحد الحقول يستخدم تجزئة الحوسبة قبل النقل (تجزئة الحوسبة تجزّئ العمود نيابةً عنك)، ستظلّ "عمليات الربط" تجزّئ هذا الحقل. يجب إبقاء قيم المصدر لهذا الحقل غير مجزأة، ولكن منسَّقة. يُرجى الاطّلاع على عمليات الربط التي تم نقلها. - في جدول مصدر BigQuery، استخدِم أعمدة
STRING.- يجب أن تكون قيم
emailوphoneوfirst_nameوlast_nameهيSTRING. أما إذا كان نوع الاتصال مختلفًا، مثلINT64، فلن تتمكّن من حفظه. - يمكن أن يكون
user_idأيضًاINT64أوBYTES. إذا لم تكن قيمةBYTESنصًا بتنسيق UTF-8، تصبحNULL. - يمكن أن يكون
zip_codeأيضًاINT64، ولكن لا يمكن أن يحتفظINT64بالصفر في بداية الرقم (يتم تخزين02134على أنه2134)، لذلك لا يمكن أن يتطابق هذا الرمز البريدي. تخزين الرموز البريدية على شكلSTRING
- يجب أن تكون قيم
- امنح كل صف رقم تعريف مستخدم. يتم احتساب جميع الصفوف التي تحتوي على رقم تعريف مستخدم
NULLكمستخدم واحد، لذا يمكن أن يتطابق صف واحد منها على الأكثر. وينطبق الشيء نفسه على جميع الصفوف التي تحتوي على رقم تعريف مستخدم فارغ. - يصبح رقم تعريف المستخدم الخاص بك
BYTES. تحوِّلها Connections إلىBYTES، وهو نوع رقم تعريف المستخدم الذي تدرجه بيانات التنسيق للإدخال، وبالتالي يمكن أن يظل عمود المصدرSTRING. على سبيل المثال، تصبح قيمةINT6442هيb"42". في جداول المطابقة "_updm"، يظهر هذا العمود باسمcustomer_data_user_id. يتعذّر تنفيذCAST(my_data.user_id AS BYTES)على معرّفINT64، لذا للانضمام إلى معرّف واحد، يجب تحويله إلىSTRINGأولاً:customer_data_user_id = CAST(CAST(my_data.user_id AS STRING) AS BYTES). - لا يمكن مطابقة قيمة فارغة أو غير صحيحة لعنوان البريد الإلكتروني أو رقم الهاتف أو العنوان، ولكن لا يؤدي ذلك إلى تعذُّر عملية المطابقة. ولا يزال بإمكان الصف مطابقة
قيمه الأخرى. على سبيل المثال، لا يمكن مطابقة عنوان بريد إلكتروني بنص عادي أو البلد
USAأو الرمز البريدي94043.1351. لمطابقة العنوان، يجب أن يحتوي الصف على قيم صالحة في جميع أعمدة العناوين الأربعة. - في طلب البحث في Private Cloud Match، يمكن أن تؤدي قيمة بتنسيق خاطئ إلى تعذُّر تنفيذ طلب البحث بالكامل. ينطبق ذلك في حال إنشاء جدول المطابقة باستخدام طلب البحث
CREATE OR REPLACE TABLE adh.updm_match_tableفي Ads Data Hub بدلاً من عملية ربط. على سبيل المثال، إذا لم يكن طول تجزئة البريد الإلكتروني 44 حرفًا، مثل تجزئة مرمّزة بنظام سداسي عشري، يتعذّر تنفيذ طلب البحث ويظهر خطأ مثلemail must be encoded using TO_BASE64(SHA256(email)). - التحقّق من نسبة المطابقة: على سبيل المثال، يمكنك استخدام طلب البحث احتساب نسبة المطابقة. لا تسجّل Connections القيم التي لا يمكن مطابقتها، ما يؤدي إلى انخفاض عدد المستخدمين المطابقين. إذا تطابق 1,000 مستخدم أو أقل، ستتعذّر عملية التشغيل مع ظهور الخطأ
Minimum match count check failed. - استخدِم اتصالاً واحدًا فقط لميزة "مطابقة البيانات المقدَّمة من المستخدم" لكل حساب. لا تتضمّن عمليات ربط ميزة "مطابقة البيانات المقدَّمة من المستخدم" جدولاً للوجهة. تكتب كل عملية ربط لميزة "مطابقة البيانات المقدَّمة من المستخدم" في حساب وكل طلب بحث في Private Cloud Match جدول المطابقة نفسه، ويتم استبداله بعد كل عملية تشغيل ناجحة. لمطابقة البيانات من عدة مصادر، ادمجها في جدول أو ملف واحد أولاً.
بيانات الطرف الأول
لكل عمود، اختَر النوع (نوع البيانات في صفحة تفاصيل الربط). تحوّل "عمليات الربط" كل قيمة مصدر إلى هذا النوع، ويحصل عمود الوجهة على نوع BigQuery المدرَج هنا:
| النوع | عمود الوجهة | القيم التي يتم تحويلها | القيم التي تصبح NULL |
|---|---|---|---|
| STRING (تلقائي) | STRING |
أي قيمة، كنص. من BigQuery، يصبح 123 "123" ويصبح TRUE "true". من Cloud Storage، يتم الاحتفاظ بالنص كما هو. |
قيمة BYTES ليست نصًا بترميز UTF-8 |
| HASH | STRING |
هو مطابق لـ STRING. لا تجري Connections تجزئة للقيمة أو تتحقّق منها. | هو مطابق لـ STRING |
| INTEGER | INT64 |
الأعداد الصحيحة ونصوص الأرقام، مثل "42". من BigQuery، يتم اقتطاع العدد العشري: يصبح 1.9 1. |
القيم الأخرى، مثل "abc" أو TRUE أو تاريخ معيّن من Cloud Storage، وهو أيضًا رقم عشري، مثل 1.9. |
| DOUBLE | FLOAT64 |
الأرقام والنصوص التي تتضمّن أرقامًا، مثل "1.5" |
قيم أخرى، مثل TRUE أو تاريخ |
| DATE | DATE |
قيم DATE، ونص السنة والشهر واليوم مثل 2026-01-15 أو 2026-1-5 |
القيم الأخرى، مثل 01/15/2026 أو 20260115 أو قيمة TIMESTAMP أو DATETIME |
| TIMESTAMP | TIMESTAMP |
القيم TIMESTAMP وDATETIME وDATE والنصوص مثل 2026-01-15 10:00:00 أو 2026-01-15T10:00:00-08:00 تتم قراءة القيمة التي لا تتضمّن منطقة زمنية على أنّها بالتوقيت العالمي المنسَّق (UTC)، ويصبح التاريخ منتصف الليل بالتوقيت العالمي المنسَّق (UTC). |
القيم الأخرى، مثل وقت حقبة يونكس (1768471200) |
- لا تؤدي القيمة التي لا يمكن تحويلها إلى تعذُّر عملية التشغيل. يتم استيرادها كـ
NULL، ولا تبلّغ عنها "عمليات الربط"، لذا يُرجى التحقّق من جدول الوجهة بعد التشغيل الأول. - اختَر النوع الذي يناسب بياناتك. بالنسبة إلى مصدر BigQuery، اختَر النوع الذي يتطابق مع عمود المصدر: STRING لـ
STRING، وINTEGER لـINT64، وDOUBLE لـFLOAT64، وDATE لـDATE، وTIMESTAMP لـTIMESTAMP. ويتم استيراد هذه القيم بدون تغيير. بالنسبة إلى مصدر Cloud Storage، كل قيمة CSV هي نص: اختَر نوع القيم في العمود، مثل INTEGER لـ42أو DATE لـ2026-01-15. إذا كان العمود يحتوي علىNULLفي كل صف، اختَر STRING أو حوِّل القيم في بيانات المصدر أولاً. - لا يمكن ربط بعض أنواع BigQuery. إذا ربطت عمود
ARRAYأوSTRUCTأوJSONأوGEOGRAPHY، لن تتمكّن من حفظ عملية الربط. - يحلّ كل تنفيذ محلّ جدول الوجهة بالكامل. ولا يتم إلحاقها. إذا لم يتضمّن المصدر أي صفوف، تصبح الوجهة فارغة. لا تستخدِم الجدول المصدر أو جدولاً تحتاج إلى الاحتفاظ ببياناته كجدول وجهة.
عمليات الربط المنقولة
لا تتوفّر عمليات التحويل بعد في تجربة "الربط" المعدَّلة: لا يمكنك إضافة عملية تحويل إلى حقل، ولا تظهر في عمليات ربط الحقول. يحتفظ الاتصال الذي تم نقله إلى تجربة "عمليات الربط" المعدَّلة بعمليات تحويل حقوله، مثل حساب التجزئة (تجزئة SHA-256).
- في عملية ربط بيانات الطرف الأول، يحصل الحقل الذي يتضمّن عملية تحويل على القيمة التي تنتجها عملية التحويل، بدلاً من تحويل النوع، ولا يمكنك تغيير نوعه. في اتصال ميزة "مطابقة البيانات المقدَّمة من المستخدم"، تظلّ قواعد هذه الميزة سارية على هذه القيمة.
- يستمر تطبيق "الربط" في تجزئة حقل "مطابقة البيانات المقدَّمة من المستخدم" الذي استخدم تجزئة الحوسبة. يجب عدم تجزئة قيم المصدر، بل تنسيقها كما هو موضّح في تنسيق البيانات للإدخال: تتم تجزئة قيمة التجزئة التي تم تجزئتها من قبل مرة أخرى ولا يمكن مطابقتها. لتجزئة القيم بنفسك بدلاً من ذلك، يُرجى إزالة عملية ربط الحقول وإضافتها مرة أخرى.
يتم نقل هذه التحويلات فقط:
- احتسِب التجزئة باستخدام SHA-256 (Base64 أو سداسي عشري)، باستثناء UPDM
user_idأوcountryأوzip_code، والتي يجب أن تظل نصًا عاديًا. - تنسيق الأحرف الصغيرة أو الكبيرة
- التحويل إلى سلسلة
- تحليل الطابع الزمني بدون منطقة زمنية تلقائية، في ما يصل إلى 10 حقول من الاتصال.
- اثنان من الثلاثة الأولى على التوالي، مثل تنسيق الأحرف الصغيرة ثم حساب التجزئة.
يتم نقل التحويل فقط إذا كان ما ينتجه يناسب حقله. بالنسبة إلى دالتَين متتاليتَين، يتم احتساب ما تنتجه الدالة الثانية: تنسيق الأحرف الصغيرة ثم حساب التجزئة يناسب
email، ولكن حساب التجزئة ثم تنسيق الأحرف الصغيرة لا يناسبه.- في اتصال ميزة "مطابقة البيانات المقدَّمة من المستخدم"، يتناسب احتساب التجزئة مع
emailوphoneوfirst_nameوlast_name. تنسيق الأحرف الصغيرة أو الكبيرة والتحويل إلى سلسلة يناسبuser_idوcountryوzip_code. لا يتطابق تحليل الطابع الزمني مع أي حقل. - في اتصال بيانات الطرف الأول، يتناسب تجزئة الحوسبة مع عمود STRING أو HASH. تنسيق الأحرف الكبيرة أو الصغيرة وتحويلها إلى سلسلة يناسب عمود STRING. يتناسب تحليل الطابع الزمني مع عمود TIMESTAMP.
لا يتم نقل أي عملية ربط تتضمّن أي تحويل آخر، مثل دمج الحقول أو تقسيمها، أو تتضمّن تحويلاً لا يتناسب مع الحقل.
- احتسِب التجزئة باستخدام SHA-256 (Base64 أو سداسي عشري)، باستثناء UPDM
متطلبات أعمدة ملفات CSV في Cloud Storage
- تضمين صفّ العنوان يتم تخطّي السطر الأول، ولا يتم استخدام أسماء الأعمدة فيه.
- يجب أن يحتوي الملف على أعمدة المصدر المرتبطة بالضبط، وليس أكثر أو أقل. تؤدي الأعمدة الإضافية إلى تعذُّر عملية التشغيل.
- بيانات الطرف الأول: يجب أن تكون الأعمدة بالترتيب نفسه لعمليات ربط الحقول.
- مطابقة البيانات المقدَّمة من المستخدم: يجب أن تكون الأعمدة بهذا الترتيب، مع الاحتفاظ
فقط بالحقول التي يتم ربطها:
user_idوemailوphoneوfirst_nameوlast_nameوcountryوzip_code. لا يهم ترتيب صفوف الربط. - لا يتم رصد ترتيب مختلف للأعمدة: يتم تحميل القيم في الحقول الخاطئة (أو تنخفض نِسب المطابقة) بدون ظهور رسالة خطأ.
مصادر البيانات المتوافقة والحدود القصوى للاتصال
- مصادر البيانات: لا تتوافق هذه الميزة إلا مع مصادر BigQuery وCloud Storage.
- أسماء جداول BigQuery: يجب أن تتضمّن جداول BigQuery المصدر والوجهة الاسم الكامل لـ
project.dataset.table. - مسارات ملفات Cloud Storage: يجب تقديم معرّف موارد منتظم (URI) لملف واحد (مثل
gs://bucket/path/file.csv). لا يمكن استخدام مسارات أحرف البدل مع*أو?. - أسماء عمليات الربط: يجب أن يكون لكل عملية ربط في الحساب اسم فريد.
تنسيق البيانات للإدخال
يجب أن تلتزم بياناتك بمتطلبات التنسيق التالية لتتم مطابقتها بشكل صحيح:
- يجب تحميل البيانات باستخدام تجزئة SHA256 في الحالات التي يُشار فيها إلى ذلك في أوصاف حقول الإدخال التالية.
- تتيح ميزة "مطابقة البيانات المقدَّمة من المستخدم" ترميز Base64. يُرجى الاطّلاع على TO_BASE64.
- يجب تنسيق حقول الإدخال كسلاسل. على سبيل المثال، إذا كنت تستخدم
دالة التجزئة SHA256 في BigQuery،
استخدِم عملية التحويل التالية:
TO_BASE64(SHA256(user_data)).
رقم تعريف المستخدم
- نوع البيانات:
BYTES - التجزئة: ما مِن تجزئة
البريد الإلكتروني
- إزالة المسافات البيضاء البادئة واللاحقة
- يجب أن تكون كل الأحرف صغيرة
- أدرِج اسم نطاق لجميع عناوين البريد الإلكتروني، مثل gmail.com أو hotmail.co.jp
- إزالة علامات التشكيل، مثل تغيير è أو é أو ê أو ë إلى e
- إزالة جميع النقاط (.) التي تسبق اسم النطاق في عناوين البريد الإلكتروني
gmail.comوgooglemail.com - التجزئة: ترميز Base64 باستخدام خوارزمية SHA256
صالح: TO_BASE64(SHA256("jeffersonloveshiking@gmail.com"))
غير صالحة: TO_BASE64(SHA256("JéffersonLôvesHiking@gmail.com"))
الهاتف
- إزالة المسافات البيضاء
- يجب استخدام تنسيق E.164، على سبيل المثال: +14155552671 في الولايات المتحدة، و+442071838750 في المملكة المتحدة
- أزِل جميع الرموز الخاصة باستثناء علامة "+" قبل رمز البلد
- التجزئة: ترميز Base64 باستخدام خوارزمية SHA256
صالح: TO_BASE64(SHA256("+18005550101"))
غير صالحة: TO_BASE64(SHA256("(800) 555-0101"))
الاسم الأول
- إزالة المسافات البيضاء
- يجب أن تكون كل الأحرف صغيرة
- يُرجى إزالة جميع البادئات، مثل السيدة السيد، الآنسة، الدكتور
- لا تُزِل علامات التشكيل، مثل è أو é أو ê أو ë
- التجزئة: ترميز Base64 باستخدام خوارزمية SHA256
صالح: TO_BASE64(SHA256("daní"))
غير صالحة: TO_BASE64(SHA256("Daní"))
اسم العائلة
- إزالة المسافات البيضاء
- يجب أن تكون كل الأحرف صغيرة
- أزِل جميع اللاحقات، مثل الابن الأب، 2nd, 3rd, II, III, PHD, MD
- لا تُزِل علامات التشكيل، مثل è أو é أو ê أو ë
- التجزئة: ترميز Base64 باستخدام خوارزمية SHA256
صالح: TO_BASE64(SHA256("délacruz"))
غير صالحة: TO_BASE64(SHA256("dé la Cruz, Jr."))
البلد
- أدرِج رمز البلد حتى إذا كانت كل بيانات العملاء واردة من البلد نفسه.
- يجب ألا تتم تجزئة بيانات البلد
- استخدِم رموز البلدان وفقًا لمعيار ISO 3166-1 alpha-2
- التجزئة: ما مِن تجزئة
صالح: US
غير صالح: United States of America أو USA
الرمز البريدي
- عدم تجزئة بيانات الرمز البريدي
- مسموح باستخدام الرموز البريدية الأمريكية والدولية
- استخدِم فقط الأحرف من A إلى Z والأرقام والمسافات والواصلات، على ألا يتجاوز عدد الأحرف 20 حرفًا
- في الولايات المتحدة:
- يُسمح باستخدام الرموز المكوَّنة من 5 أرقام، مثل 94043
- يُسمح أيضًا باستخدام 5 أرقام متبوعة بإضافة مكوّنة من 4 أرقام، مثل 94043-1351 أو 940431351
- بالنسبة إلى جميع البلدان الأخرى:
- لا حاجة إلى تحويل الأحرف إلى أحرف صغيرة أو إزالة المسافات والواصلات
- يجب استبعاد إضافات الرموز البريدية
- التجزئة: ما مِن تجزئة
التحقّق من صحة التجزئة وترميز البيانات
يمكنك استخدام نصوص التحقّق من التجزئة التالية للتأكّد من تنسيق بياناتك بشكل صحيح.
JavaScript
/**
* @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
"""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
/*
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")
}
جافا
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
/*
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`;
مفاتيح الدمج
بعض مجموعات البيانات المقدَّمة من المستخدم تكون أقوى من غيرها. في ما يلي قائمة بمجموعات مختلفة من البيانات المقدَّمة من المستخدم، مرتّبة حسب القوة النسبية. إذا كنت تستخدم عنوانًا، يجب تضمين: الاسم الأول واسم العائلة والبلد والرمز البريدي.
- البريد الإلكتروني ورقم الهاتف والعنوان (الأقوى)
- رقم الهاتف والعنوان
- البريد الإلكتروني والعنوان
- البريد الإلكتروني والهاتف
- العنوان
- الهاتف
- البريد الإلكتروني (الأضعف)
إنشاء جدول مطابقات
- انقر على add إنشاء > طلب بحث.
انسخ نموذج طلب البحث إنشاء جدول المطابقة في السحابة الإلكترونية الخاصة والصِقه في محرِّر طلبات البحث. اختياري: يمكنك استخدام نموذج إنشاء جدول المطابقة في السحابة الإلكترونية الخاصة (مع التجزئة) إذا لم تكن بياناتك مجزّأة.
/* Private cloud match table generation Create a new match table using your first party data with this template. Parameters: Manually remove all the parameters tagged with @ prefix and replace them with column names from your first party table: * @user_id * @email * @phone * @first_name * @last_name * @country_code * @postal_code And your BigQuery table information: * @my_project: Your BigQuery project where the first party table is. * @my_dataset: Your dataset where the first party table is. * @my_first_party_table: Your first party table. */ CREATE OR REPLACE TABLE adh.updm_match_table AS ( SELECT CAST(@user_id AS BYTES) AS user_id, @email AS email, @phone AS phone, @first_name AS first_name, @last_name AS last_name, @country_code AS country, @postal_code AS zip_code FROM `@my_project.@my_dataset.@my_first_party_table` );/* Private cloud match table generation (with hashing) Create a new match table using your first party data with this template. Parameters: Manually remove all the parameters tagged with @ prefix and replace them with column names from your first party table: * @user_id * @email * @phone * @first_name * @last_name * @country_code * @postal_code And your BigQuery table information: * @my_project : Your BigQuery project where the first party table is. * @my_dataset : Your dataset where the first party table is. * @my_first_party_table : Your first party table. */ CREATE OR REPLACE TABLE adh.updm_match_table AS ( SELECT CAST(@user_id AS BYTES) AS user_id, TO_BASE64(SHA256(LOWER(@email))) AS email, TO_BASE64(SHA256(@phone)) AS phone, TO_BASE64(SHA256(LOWER(@first_name))) AS first_name, TO_BASE64(SHA256(LOWER(@last_name))) AS last_name, @country_code AS country, @postal_code AS zip_code FROM `@my_project.@my_dataset.@my_first_party_table` );استبدِل أسماء المَعلمات بأسماء الأعمدة لتقديم أسماء بديلة مناسبة.
انقر على حفظ.
انقر على تشغيل. عليك تنفيذ طلب البحث هذا يدويًا لإعادة تحميل جدول المطابقة. سيؤدي كل تشغيل إلى استبدال جدول المطابقة الحالي.
نقل عمليات الربط الحالية
سيتم نقل عمليات الربط الحالية في علامة التبويب عمليات الربط إلى تجربة "عمليات الربط" المعدَّلة المضمّنة مباشرةً في Ads Data Hub. تقرأ الاتصالات المعدَّلة المصادر وتكتب الوجهات باستخدام حساب الخدمة المعروض ضمن الإعدادات > التفاصيل > حساب الخدمة (عادةً service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com) بدلاً من حسابات خدمة Data Fusion وDataproc وUPDM القديمة.
يُرجى إكمال بنود العمل هذه قبل نقل عمليات الربط:
- منح أذونات حساب الخدمة: امنح حساب الخدمة المعروض ضمن
الإعدادات > التفاصيل > حساب الخدمة (عادةً
service-<number>@gcp-sa-adsdatahub.iam.gserviceaccount.com) أدوار المصدر والوجهة المطلوبة (roles/bigquery.dataViewerوroles/storage.objectViewerوroles/bigquery.dataEditorفي مجموعات بيانات الوجهة غير التلقائية). قد يستمر نقل عمليات الربط التي تتضمّن مصادر غير قابلة للقراءة أو محذوفة أو تم تغييرها (خاصةً مصادر Cloud Storage التي لا يتم التحقّق منها في وقت النقل)، ولكن ستتعذّر عمليات الربط إلى أن تمنح الإذن بالوصول أو تصلح المصدر. تحويل الاتصالات غير المتوافقة: لن يتم نقل الاتصالات التي تتضمّن الإعدادات التالية. يمكنك تحويلها إلى اتصالات متوافقة مع BigQuery أو Cloud Storage:
- مصادر البيانات الأخرى (Amazon S3 أو Snowflake أو MySQL أو PostgreSQL أو Amazon Redshift أو sFTP أو Salesforce): عليك تنظيم البيانات في BigQuery أو Cloud Storage أولاً، ثم إنشاء عملية ربط بـ BigQuery أو Cloud Storage.
- عمليات ربط الحقول أو أنواع البيانات غير المتوافقة: عدِّل عملية الربط أو أعِد إنشاءها لتلبية متطلبات الحقول وأنواع البيانات.
- عمليات التحويل غير المتوافقة: يتم نقل عمليات التحويل المُدرَجة في عمليات الربط المنقولة فقط. أزِل أي تحويل آخر، مثل دمج الحقول أو تقسيمها، ونفِّذ هذا العمل في بيانات المصدر بدلاً من ذلك.
- مسارات أحرف البدل في Cloud Storage (
*أو?): استبدِل معرّف الموارد المنتظم (URI) لأحرف البدل بمعرّف الموارد المنتظم (URI) لملف واحد أو حمِّل الملفات إلى BigQuery أولاً. - الأسماء المستخدَمة حاليًا في Ads Data Hub: أعِد تسمية الاتصال إذا كان هناك طلب بحث أو اتصال تم إنشاؤه في تجربة "عمليات الربط" المعدَّلة يحمل الاسم نفسه في حسابك.
يتم نقل عمليات الربط الحالية التي تشترك في الاسم نفسه: يحتفظ أقدمها بالاسم، وتحصل العمليات الأخرى على لاحقة، مثل
(2)أو(3).حذف عمليات الربط غير المستخدَمة: احذف عمليات الربط القديمة التي لم تعُد بحاجة إليها.
البيانات المطابقة لطلب البحث
الاستعلام عن جداول المطابقة
عندما تحتوي جداول المطابقة على بيانات كافية لاستيفاء عمليات التحقّق من الخصوصية، تكون مستعدًا لتنفيذ طلبات البحث في الجداول.
يتم تمثيل الجدول الأصلي لبيانات الطرف الأول (1PD) من خلال my_data.
ويشمل ذلك كلاً من المعلومات التي تكشف الهوية الشخصية (PII) والبيانات التي لا تكشف الهوية الشخصية.
يمكن أن يؤدي استخدام الجدول الأصلي إلى تحسين تقاريرك من خلال تقديم المزيد من الإحصاءات، لأنّه
يمثّل جميع بيانات الطرف الأول ضمن النطاق، مقارنةً بجدول المطابقة.
كل جدول في مخطط 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
احتساب نسبة المطابقة
لا يكون بعض المستخدمين مؤهَّلين للمطابقة. على سبيل المثال، لا تتم مطابقة المستخدمين الذين سجّلوا الخروج من حساباتهم والأطفال والمستخدمين الذين لم يمنحوا الموافقة من خلال ميزة "مطابقة البيانات المقدَّمة من المستخدم". يمكنك استخدام حقل 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
الأسئلة الشائعة حول ميزة "مطابقة البيانات المقدَّمة من المستخدم"
للاطّلاع على قائمة بالأسئلة الشائعة حول ميزة "مطابقة البيانات المقدَّمة من المستخدم"، يُرجى مراجعة الأسئلة الشائعة حول ميزة "مطابقة البيانات المقدَّمة من المستخدم".