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

تتيح واجهة 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: أزِل جميع النقاط (.) قبل الرمز @. أزِل علامة الجمع (+) من الجزء المحلي وأزِل جميع الأحرف التي تليها. مثال: [e-mail] ← [e-mail] إذا كان عنوان البريد الإلكتروني يحتوي على نطاق غير gmail.com أو googlemail.com، لا تُزِل النقاط أو علامات الجمع. مثال: [e-mail] ← [e-mail] مسافة بيضاء إزالة المسافات البيضاء البادئة واللاحقة والمتوسطة التجزئة يجب تجزئة البيانات باستخدام خوارزمية SHA-256 وترميز وحدات بايت التجزئة.
phone_number	التنسيق string استخدِم تنسيق E.164. يجب تضمين علامة الجمع (+) ورمز البلد. يجب أن تكون جميع الأحرف بعد علامة الجمع أرقامًا. على سبيل المثال، يجب تنسيق رقم الهاتف في الولايات المتحدة [phone] وتسويته إلى [phone]. مسافة بيضاء يجب إزالة المسافات البيضاء البادئة واللاحقة. التجزئة يجب تجزئة البيانات باستخدام خوارزمية SHA-256 وترميز وحدات بايت التجزئة.
address	AddressInfo object يُرجى الرجوع إلى مواصفات تنسيق AddressInfo.

صيغة AddressInfo

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

AddressInfo
given_name	التنسيق string تحويل النص إلى أحرف لاتينية صغيرة لا تُدرِج بادئات مثل Mrs. مسافة بيضاء يجب إزالة المسافات البيضاء البادئة واللاحقة. التجزئة يجب تجزئة البيانات باستخدام خوارزمية SHA-256 وترميز وحدات بايت التجزئة.
family_name	التنسيق string تحويل النص إلى أحرف لاتينية صغيرة لا تُدرِج لاحقات مثل Jr. مسافة بيضاء يجب إزالة المسافات البيضاء البادئة واللاحقة. التجزئة يجب تجزئة البيانات باستخدام خوارزمية SHA-256 وترميز وحدات بايت التجزئة.
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 وترميز وحدات بايت التجزئة.
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 ومناطق زمنية مختلفة:

• المنطقة الزمنية للتوقيت العالمي المتفق عليه: 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 ساعات ولا تتبع نظام التوقيت الصيفي: 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

الترميز

تختلف متطلبات الترميز حسب ما إذا كنت تشفّر بيانات المستخدمين:

• بيانات المستخدمين غير المشفّرة: يمكنك ترميز وحدات بايت تجزئة SHA-256 باستخدام الترميز السداسي العشري (hex) أو ترميز Base64.

• بيانات المستخدمين المشفَّرة: إذا كنت تشفِّر بيانات المستخدمين، عليك ترميز وحدات بايت التجزئة الأولية باستخدام Base64 قبل التشفير. لا يتوفّر ترميز نظام العد الستة عشري لتجزئة ما قبل التشفير. يمكنك بعد ذلك ترميز النص المشفّر الناتج باستخدام نظام العد الستة عشري أو ترميز Base64.

ملاحظة: لا تهمّ حالة الأحرف في مخرجات الترميز عند استخدام ترميز نظام العد الستة عشري.