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

تتيح 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. رمِّز وحدات البايت الخاصة بالتجزئة باستخدام ترميز سداسي عشري أو 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. يجب تشفير وحدات البايت الخاصة بالتجزئة باستخدام تشفير تبادلي لمنحنى إهليلجي باستخدام مفتاح الناشر لقائمة مستخدمي PAIR.
  3. رمِّز البيانات المشفّرة باستخدام ترميز hex أو Base64.

متطلبات MobileData

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

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

في حال استخدام تنسيق JSON للحقول Timestamp، مثل timestamp وlast_updated_timestamp في Event، استخدِم تنسيق RFC 3339. في ما يلي بعض الأمثلة على توقيت غرينتش في 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

الترميز

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

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