فرمت داده های کاربر

رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API) از آپلود انواع مختلف داده‌های کاربر پشتیبانی می‌کند. الزامات قالب‌بندی، هش کردن و کدگذاری را برای هر عنصر داده رعایت کنید تا داده‌های شما با موفقیت دریافت و پردازش شوند.

الزامات UserData

یک شیء UserData مجموعه‌ای از اشیاء UserIdentifier است. هر UserIdentifier دقیقاً یکی از ویژگی‌های جدول زیر را دارد.

شناسه کاربری
email_address
قالب
string
  • به حروف کوچک تبدیل کنید.
  • اگر آدرس ایمیل دارای دامنه gmail.com یا googlemail.com است:
    • تمام نقطه‌ها ( . ) قبل از نماد @ را حذف کنید.
    • علامت جمع ( + ) را از قسمت محلی (local-part) حذف کنید و تمام کاراکترهای بعد از آن را نیز حذف کنید.
    • مثال: 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

از دستورالعمل‌های قالب‌بندی زیر برای ساخت ویژگی address یک UserIdentifier استفاده کنید.

اطلاعات آدرس
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
کد پستی و پستی ایالات متحده و بین‌المللی هر دو مجاز هستند.
برای آدرس‌های ایالات متحده، از ۵ رقم یا ۵ رقم و به دنبال آن یک شماره داخلی ۴ رقمی استفاده کنید. استفاده از یک شماره داخلی ۴ رقمی ممکن است نرخ تطابق شما را بهبود بخشد.
برای سایر کشورها، از پسوندهای کد پستی استفاده نکنید.
فضای سفید فاصله‌های خالیِ ابتدا و انتهای متن را حذف کنید.
هش کردن postal_code هش نکنید.
address_line
قالب
string
فقط برای گوگل آنالیتیکس استفاده می‌شود.
خیابان و شماره آدرس کاربر.
به حروف کوچک تبدیل کنید.
حذف کاراکترهای نماد.
فضای سفید فاصله‌های خالیِ ابتدا و انتهای متن را حذف کنید.
هش کردن با استفاده از الگوریتم SHA-256 هش کنید. بایت‌های هش را با استفاده از کدگذاری هگز یا Base64 رمزگذاری کنید.
city
قالب
string
فقط برای گوگل آنالیتیکس استفاده می‌شود.
شهر آدرس کاربر.
به حروف کوچک تبدیل کنید.
حذف کاراکترهای نماد.
فضای سفید فاصله‌های خالیِ ابتدا و انتهای متن را حذف کنید.
هش کردن city هش نکن.
administrative_area
قالب
string
فقط برای گوگل آنالیتیکس استفاده می‌شود.
منطقه اداری (ایالت یا استان) آدرس کاربر.
یا از مخفف دو حرفی (مثلاً ca ) یا از نام کامل (مثلاً california ) استفاده کنید.
به حروف کوچک تبدیل کنید.
حذف کاراکترهای نماد.
فضای سفید فاصله‌های خالیِ ابتدا و انتهای متن را حذف کنید.
هش کردن administrative_area را هش نکنید.

الزامات IpData

یک شیء IpData دارای ویژگی‌های زیر است.

آی‌پی‌دیتا
ip_address
قالب
string
آدرس IPv4 یا IPv6.
برای آدرس‌های IPv6، حروف کوچک و بزرگ اهمیتی ندارند (می‌توان از حروف بزرگ یا کوچک استفاده کرد).
فضای سفید فاصله‌های خالیِ ابتدا و انتهای متن را حذف کنید.
هش کردن ip_address هش نکنید.

الزامات PairData

فیلد pair_ids از یک شیء PairData را با لیستی از شناسه‌ها پر کنید. هر عنصر در لیست را با استفاده از مراحل زیر قالب‌بندی کنید:

  1. داده‌های PII ارائه شده توسط اتاق تمیز را با استفاده از الگوریتم SHA-256 هش کنید.
  2. بایت‌های هش را با یک رمز جابجایی EC و با استفاده از کلید ناشر برای لیست کاربران PAIR رمزگذاری کنید.
  3. داده‌های رمزگذاری شده را با استفاده از کدگذاری هگز یا Base64 رمزگذاری کنید.

الزامات MobileData

فیلد mobile_ids از شیء MobileData را با لیستی از شناسه‌های تلفن همراه پر کنید. شناسه‌های تلفن همراه را هش نکنید.

قالب مهر زمانی

اگر از فرمت JSON برای فیلدهای Timestamp ، مانند timestamp و last_updated_timestamp مربوط به Event ، استفاده می‌کنید، از فرمت RFC 3339 استفاده کنید. در اینجا چند نمونه از زمان UTC مربوط به ۸ آگوست ۲۰۲۵، ساعت ۵:۱۸:۴۴.۲۹۱ بعد از ظهر در فرمت RFC 3339 و مناطق زمانی مختلف آورده شده است:

  • منطقه زمانی UTC: 2025-08-08T17:18:44.291Z
  • منطقه زمانی EDT، که در آن زمان ۴ ساعت قبل از UTC بود: 2025-08-08T13:18:44.291-04:00
  • منطقه زمانی PDT، که در آن زمان ۷ ساعت قبل از UTC بود: 2025-08-08T10:18:44.291-07:00
  • منطقه زمانی توکیو، ژاپن، که ۹ ساعت از UTC جلوتر بود و ساعت تابستانی را رعایت نمی‌کند: 2025-08-08T22:18:44.291+09:00

اگر از قالب بافر پروتکل استفاده می‌کنید، هنگام ساخت Timestamp seconds و به صورت اختیاری، nanos تنظیم کنید. در اینجا مقادیر seconds و nanos برای زمان UTC در تاریخ ۸ آگوست ۲۰۲۵، ساعت ۵:۱۸:۴۴.۲۹۱ بعد از ظهر آمده است:

  • seconds : 1754683124
  • nanos : 291000000

رمزگذاری

هنگام کدگذاری داده‌ها، نکات زیر را در نظر داشته باشید:

  • هنگام استفاده از کدگذاری هگزادسیمال (hexadecimal)، حروف کوچک و بزرگ خروجی کدگذاری اهمیتی ندارند.
  • هنگام استفاده از کدگذاری Base64، بزرگی یا کوچکی خروجی کدگذاری اهمیت دارد .
قبلی
پیکربندی مقصدها و سرآیندها
بعدی
رمزگذاری داده های کاربر