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

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

  • UserData: البيانات المقدَّمة من المستخدِم، مثل عنوان البريد الإلكتروني أو رقم الهاتف
  • ‫IpData: بيانات IP، مثل عنوان IP والطوابع الزمنية المرتبطة به
  • ‫PairData: معرّفات Publisher Advertiser Identity Reconciliation (PAIR)
  • ‫MobileData: بيانات تحدّد جهازًا جوّالاً.

متطلبات 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 رمِّز وحدات البايت المجزّأة باستخدام ترميز 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.
address_line
التنسيق
string
تُستخدَم فقط لخدمة "إحصاءات Google".
يشير ذلك إلى الشارع ورقم عنوان المستخدِم.
تحويل إلى أحرف صغيرة
إزالة رموز الأحرف
مسافة بيضاء إزالة المسافات البيضاء البادئة واللاحقة
التجزئة تجزئة البيانات باستخدام خوارزمية SHA-256 رمِّز وحدات البايت المجزّأة باستخدام ترميز hex أو 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. يجب تشفير وحدات البايت الخاصة بالتجزئة باستخدام تشفير تبادلي لمنحنى إهليلجي باستخدام مفتاح الناشر لقائمة مستخدمي 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

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

  • seconds: 1754683124
  • nanos: 291000000

الترميز

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

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