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

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

متطلبات UserData

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

UserIdentifier
email_address
التنسيق
string
يجب تحويلها إلى أحرف لاتينية صغيرة.
إذا كان عنوان البريد الإلكتروني يتضمّن النطاق gmail.com أو googlemail.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.

متطلبات 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

الترميز

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

  • لا يهمّ استخدام الأحرف اللاتينية الكبيرة أو الصغيرة في ناتج الترميز عند استخدام الترميز السداسي العشري.
  • يهمّ استخدام الأحرف اللاتينية الكبيرة أو الصغيرة في ناتج الترميز عند استخدام ترميز Base64 encoding.
السابق
ضبط الوجهات والعناوين
التالي
تشفير بيانات المستخدمين