تنسيق بيانات المستخدمين

تتيح Data Manager API تحميل أنواع متعدّدة من بيانات المستخدمين. يُرجى اتّباع متطلبات التنسيق والتجزئة والترميز لكل عنصر من عناصر البيانات لضمان تلقّي بياناتك ومعالجتها بنجاح.

متطلبات UserData

كائن UserData هو مجموعة من كائنات UserIdentifier. يحتوي كل كائن UserIdentifier على سمة واحدة فقط من السمات الواردة في الجدول التالي.

UserIdentifier
email_address
التنسيق
string
  • يجب تحويل الأحرف إلى أحرف صغيرة.
  • إذا كان عنوان البريد الإلكتروني يتضمّن النطاق gmail.com أو googlemail.com:
    • يجب إزالة جميع النقاط (.) قبل الرمز @.
    • يجب إزالة علامة الجمع (+) من الجزء المحلي وإزالة جميع الأحرف التي تليها.
    • مثال: cloudy.sanfrancisco+shopping@gmail.com ← cloudysanfrancisco@gmail.com
  • إذا كان عنوان البريد الإلكتروني يتضمّن نطاقًا آخر غير gmail.com أو googlemail.com، لا تتم إزالة النقاط أو علامات الجمع.
    • مثال: user.name+NYC@Example.com ← user.name+nyc@example.com
مسافة بيضاء يجب إزالة المسافات البيضاء في بداية السطر ونهايته وفي وسطه.
التجزئة يجب التجزئة باستخدام خوارزمية SHA-256. يجب ترميز وحدات البايت المجزّأة باستخدام الترميز السداسي العشري أو ترميز Base64.
phone_number
التنسيق
string
يجب استخدام تنسيق E.164.
يجب تضمين علامة الجمع (+) ورمز البلد ( ). يجب أن تكون جميع الأحرف بعد علامة الجمع أرقامًا.
على سبيل المثال، يجب تنسيق رقم الهاتف الأمريكي (800)555-0100 وتعديله ليصبح +18005550100.
مسافة بيضاء يجب إزالة المسافات البيضاء في بداية السطر ونهايته.
التجزئة يجب التجزئة باستخدام خوارزمية SHA-256. يجب ترميز وحدات البايت المجزّأة باستخدام الترميز السداسي العشري أو ترميز Base64.
address
AddressInfo كائن
يُرجى الرجوع إلى AddressInfo مواصفات التنسيق.

تنسيق AddressInfo

يُرجى اتّباع إرشادات التنسيق التالية لإنشاء السمة address في UserIdentifier.

AddressInfo
given_name
التنسيق
string
يجب تحويل الأحرف إلى أحرف صغيرة.
لا يجب تضمين البادئات، مثل Mrs.
مسافة بيضاء يجب إزالة المسافات البيضاء في بداية السطر ونهايته.
التجزئة يجب التجزئة باستخدام خوارزمية SHA-256. يجب ترميز وحدات البايت المجزّأة باستخدام الترميز السداسي العشري أو ترميز Base64.
family_name
التنسيق
string
يجب تحويل الأحرف إلى أحرف صغيرة.
لا يجب تضمين اللواحق، مثل Jr.
مسافة بيضاء يجب إزالة المسافات البيضاء في بداية السطر ونهايته.
التجزئة يجب التجزئة باستخدام خوارزمية SHA-256. يجب ترميز وحدات البايت المجزّأة باستخدام الترميز السداسي العشري أو ترميز Base64.
region_code
التنسيق
string
رمز مكوّن من حرفَين وفقًا للمعيار ISO-3166-1 alpha-2.
مسافة بيضاء يجب إزالة المسافات البيضاء في بداية السطر ونهايته.
التجزئة لا يجب تجزئة region_code.
postal_code
التنسيق
string
يُسمح باستخدام الرموز البريدية الأمريكية والدولية.
بالنسبة إلى العناوين في الولايات المتحدة، يجب استخدام إما 5 أرقام أو 5 أرقام متبوعة بامتداد مكوّن من 4 أرقام. قد يؤدي استخدام امتداد مكوّن من 4 أرقام إلى تحسين معدّل المطابقة.
بالنسبة إلى جميع البلدان الأخرى، لا يجب استخدام امتدادات الرموز البريدية.
مسافة بيضاء يجب إزالة المسافات البيضاء في بداية السطر ونهايته.
التجزئة لا يجب تجزئة postal_code.
address_line
التنسيق
string
يُستخدم هذا الحقل فقط في "إحصاءات Google".
يشمل هذا الحقل الشارع ورقم عنوان المستخدم.
يجب تحويل الأحرف إلى أحرف صغيرة.
يجب إزالة الأحرف الرمزية.
مسافة بيضاء يجب إزالة المسافات البيضاء في بداية السطر ونهايته.
التجزئة يجب التجزئة باستخدام خوارزمية SHA-256. يجب ترميز وحدات البايت المجزّأة باستخدام الترميز السداسي العشري أو ترميز Base64.
city
التنسيق
string
يُستخدم هذا الحقل فقط في "إحصاءات Google".
يشمل هذا الحقل مدينة عنوان المستخدم.
يجب تحويل الأحرف إلى أحرف صغيرة.
يجب إزالة الأحرف الرمزية.
مسافة بيضاء يجب إزالة المسافات البيضاء في بداية السطر ونهايته.
التجزئة لا يجب تجزئة city.
administrative_area
التنسيق
string
يُستخدم هذا الحقل فقط في "إحصاءات Google".
يشمل هذا الحقل المنطقة الإدارية (الولاية أو المقاطعة) لعنوان المستخدم.
يجب استخدام إما الاختصار المكوّن من حرفَين (مثل ca) أو الاسم الكامل (مثل california).
يجب تحويل الأحرف إلى أحرف صغيرة.
يجب إزالة الأحرف الرمزية.
مسافة بيضاء يجب إزالة المسافات البيضاء في بداية السطر ونهايته.
التجزئة لا يجب تجزئة administrative_area.

متطلبات IpData

يحتوي كائن IpData على السمات التالية.

IpData
ip_address
التنسيق
string
عنوان IPv4 أو IPv6
بالنسبة إلى عناوين IPv6، لا يهم ما إذا كانت الأحرف كبيرة أو صغيرة.
مسافة بيضاء يجب إزالة المسافات البيضاء في بداية السطر ونهايته.
التجزئة لا يجب تجزئة ip_address.

متطلبات PairData

يجب ملء حقل pair_ids في كائن PairData بقائمة من المعرّفات. يجب تنسيق كل عنصر في القائمة باتّباع الخطوات التالية:

  1. يجب تجزئة بيانات المعلومات التي تكشف الهوية الشخصية التي يقدّمها الغرفة النظيفة باستخدام خوارزمية SHA-256.
  2. يجب تشفير وحدات البايت المجزّأة باستخدام تشفير تبادلي EC باستخدام مفتاح الناشر لقائمة مستخدمي PAIR.
  3. يجب ترميز البيانات المشفّرة باستخدام الترميز السداسي العشري أو ترميز Base64.

متطلبات MobileData

يجب ملء حقل mobile_ids في كائن MobileData بقائمة من معرّفات الأجهزة الجوّالة. لا يجب تجزئة معرّفات الأجهزة الجوّالة.

تنسيق الطابع الزمني

في حال استخدام تنسيق JSON لحقول Timestamp، مثل timestamp و last_updated_timestamp في Event، يجب استخدام تنسيق RFC 3339. في ما يلي بعض الأمثلة على التوقيت العالمي المنسّق (UTC) في 8 أغسطس 2025 الساعة 5:18:44.291 مساءً بتنسيق RFC 3339 ومناطق زمنية مختلفة:

  • المنطقة الزمنية للتوقيت العالمي المنسّق (UTC): 2025-08-08T17:18:44.291Z
  • المنطقة الزمنية للتوقيت الصيفي لشرق الولايات المتحدة (EDT)، التي كانت قبل 4 ساعات من التوقيت العالمي المنسّق (UTC) في ذلك الوقت: 2025-08-08T13:18:44.291-04:00
  • المنطقة الزمنية للتوقيت الصيفي للمحيط الهادئ (PDT)، التي كانت قبل 7 ساعات من التوقيت العالمي المنسّق (UTC) في ذلك الوقت: 2025-08-08T10:18:44.291-07:00
  • المنطقة الزمنية لطوكيو في اليابان، التي كانت متقدّمة بـ 9 ساعات عن التوقيت العالمي المنسّق (UTC) ولا تستخدم نظام التوقيت الصيفي: 2025-08-08T22:18:44.291+09:00

في حال استخدام تنسيق المخزن المؤقت للبروتوكول، يجب ضبط seconds وnanos (اختياريًا) عند إنشاء Timestamp. في ما يلي قيمتا seconds وnanos للتوقيت العالمي المنسّق (UTC) في 8 أغسطس 2025 الساعة 5:18:44.291 مساءً:

  • seconds: 1754683124
  • nanos: 291000000

الترميز

يجب مراعاة ما يلي عند ترميز البيانات:

السابق
ضبط الوجهات والعناوين
التالي
تشفير بيانات المستخدمين