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

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

متطلبات UserData

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

UserIdentifier
email_address
التنسيق
string
تحويل إلى أحرف صغيرة
إذا كان عنوان البريد الإلكتروني يتضمّن النطاق gmail.com أو googlemail.com، أزِل جميع النقاط (.) قبل الرمز @.
مسافة بيضاء إزالة المسافات البيضاء البادئة واللاحقة والمتوسطة
التجزئة يجب التجزئة باستخدام خوارزمية SHA-256. رمِّز وحدات البايت المجزّأة باستخدام ترميز hex أو Base64.
phone_number
التنسيق
string
استخدِم تنسيق E.164.
يجب تضمين علامة الجمع (+) ورمز البلد. يجب أن تكون جميع الأحرف بعد علامة الجمع أرقامًا.
على سبيل المثال، يجب تنسيق رقم الهاتف الأمريكي (800)555-0100 وتسويته إلى +18005550100.
مسافة بيضاء إزالة المسافات البيضاء البادئة واللاحقة
التجزئة يجب التجزئة باستخدام خوارزمية SHA-256. رمِّز وحدات البايت المجزّأة باستخدام ترميز hex أو Base64.
address
يمكنك الرجوع إلى AddressInfo مواصفات التنسيق.

صيغة AddressInfo

استخدِم إرشادات التنسيق التالية لإنشاء السمة address الخاصة بـ UserIdentifier.

AddressInfo
given_name
التنسيق
string
تحويل إلى أحرف صغيرة
لا تُدرِج بادئات مثل Mrs.
مسافة بيضاء إزالة المسافات البيضاء البادئة واللاحقة
التجزئة يجب التجزئة باستخدام خوارزمية SHA-256. رمِّز وحدات البايت المجزّأة باستخدام ترميز hex أو Base64.
family_name
التنسيق
string
تحويل إلى أحرف صغيرة
لا تُدرِج لاحقات مثل Jr.
مسافة بيضاء إزالة المسافات البيضاء البادئة واللاحقة
التجزئة يجب التجزئة باستخدام خوارزمية SHA-256. رمِّز وحدات البايت المجزّأة باستخدام ترميز hex أو Base64.
region_code
التنسيق
string
رمز ISO-3166-1 alpha-2 مكوّن من حرفين
مسافة بيضاء إزالة المسافات البيضاء البادئة واللاحقة
التجزئة لا تجزّئ region_code.
postal_code
التنسيق
string
مسموح باستخدام الرموز البريدية الأمريكية والدولية.
بالنسبة إلى العناوين في الولايات المتحدة، استخدِم إما 5 أرقام أو 5 أرقام متبوعة برقم إضافي مكوّن من 4 أرقام. قد يؤدي استخدام إضافة مكوّنة من 4 أرقام إلى تحسين نسبة المطابقة.
بالنسبة إلى جميع البلدان الأخرى، لا تستخدِم إضافات الرموز البريدية.
مسافة بيضاء إزالة المسافات البيضاء البادئة واللاحقة
التجزئة لا تجزّئ postal_code.

متطلبات PairData

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

  1. جزِّئ بيانات معلومات تحديد الهوية الشخصية المقدَّمة من مساحة العرض المحمي باستخدام خوارزمية SHA-256.
  2. يتم تشفير وحدات البايت الخاصة بالتجزئة باستخدام تشفير تبادلي لمنحنى قطع ناقص (EC) باستخدام مفتاح الناشر لقائمة المستخدمين PAIR.
  3. رمِّز البيانات المشفّرة باستخدام ترميز hex أو Base64.

متطلبات MobileData

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

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

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

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

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

  • seconds: 1754683124
  • nanos: 291000000

الترميز

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

الخطوات التالية