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

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

• UserData : داده‌های ارائه شده توسط کاربر مانند آدرس ایمیل یا شماره تلفن.
• IpData : داده‌های IP مانند آدرس IP و مهرهای زمانی مرتبط.
• PairData : شناسه‌های تطبیق هویت ناشر و تبلیغ‌کننده (PAIR).
• MobileData : داده‌هایی که یک دستگاه تلفن همراه را شناسایی می‌کنند.

الزامات UserData

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

شناسه کاربری
email_address	قالب string به حروف کوچک تبدیل کنید. اگر آدرس ایمیل دارای دامنه gmail.com یا googlemail.com است: تمام نقطه‌ها ( . ) قبل از نماد @ را حذف کنید. علامت جمع ( + ) را از قسمت محلی (local-part) حذف کنید و تمام کاراکترهای بعد از آن را نیز حذف کنید. مثال: [e-mail] → [e-mail] اگر آدرس ایمیل دامنه‌ای غیر از gmail.com یا googlemail.com دارد، نقطه‌ها یا علامت‌های بعلاوه را حذف نکنید. مثال: [e-mail] → [e-mail] فضای سفید فاصله‌های خالیِ ابتدا، انتهای و وسط را حذف کنید. هش کردن با استفاده از الگوریتم SHA-256 هش کنید. بایت‌های هش را با استفاده از کدگذاری هگز یا Base64 رمزگذاری کنید.
phone_number	قالب string از فرمت E.164 استفاده کنید. علامت جمع ( + ) و کد کشور را وارد کنید. تمام کاراکترهای بعد از علامت جمع باید عدد باشند. برای مثال، شماره تلفن ایالات متحده [phone] باید به صورت [phone] ‎ قالب‌بندی و نرمال‌سازی شود. فضای سفید فاصله‌های خالیِ ابتدا و انتهای متن را حذف کنید. هش کردن با استفاده از الگوریتم SHA-256 هش کنید. بایت‌های هش را با استفاده از کدگذاری هگز یا Base64 رمزگذاری کنید.
address	AddressInfo به مشخصات قالب 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 هش نکنید.

الزامات 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، بزرگی یا کوچکی خروجی کدگذاری اهمیت دارد .