قالب‌بندی داده‌های کاربر

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

الزامات 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 درهم‌سازی کنید و بایت‌های درهم‌سازی را کدبندی کنید.
phone_number
قالب
string
از قالب E.164 استفاده کنید.
علامت مثبت (+) و کد کشور را وارد کنید. همه نویسه‌های بعداز علامت جمع باید عدد باشند.
برای مثال، شماره تلفن ایالات متحده (800)555-0100 باید قالب‌بندی و به +18005550100 نرمال‌سازی شود.
فاصله سفید فاصله سفید اضافی در ابتدا و انتهای متن را حذف کنید.
درهم‌سازی بااستفاده از الگوریتم SHA-256 درهم‌سازی کنید و بایت‌های درهم‌سازی را کدبندی کنید.
address
به 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
کدهای پستی ایالات متحده و بین‌المللی مجاز هستند.
برای نشانی‌های ایالات متحده، از ۵ رقم یا ۵ رقم به‌همراه ۴ رقم داخلی استفاده کنید. استفاده از پیش‌شماره ۴ رقمی می‌تواند نرخ مطابقت شما را بهبود دهد.
برای همه کشورهای دیگر، از پسوند کد پستی استفاده نکنید.
فاصله سفید فاصله سفید اضافی در ابتدا و انتهای متن را حذف کنید.
درهم‌سازی postal_code را درهم‌سازی نکنید.
address_line
قالب
string
فقط برای Google Analytics استفاده می‌شود.
خیابان و شماره نشانی کاربر.
تبدیل به حروف کوچک.
نویسه‌های نماد را بردارید.
فاصله سفید فاصله سفید اضافی در ابتدا و انتهای متن را حذف کنید.
درهم‌سازی بااستفاده از الگوریتم SHA-256 درهم‌سازی کنید و بایت‌های درهم‌سازی را کدبندی کنید.
city
قالب
string
فقط برای Google Analytics استفاده می‌شود.
شهر نشانی کاربر.
تبدیل به حروف کوچک.
نویسه‌های نماد را بردارید.
فاصله سفید فاصله سفید اضافی در ابتدا و انتهای متن را حذف کنید.
درهم‌سازی city را درهم‌سازی نکنید.
administrative_area
قالب
string
فقط برای Google Analytics استفاده می‌شود.
تقسیمات کشوری (ایالت یا استان) نشانی کاربر.
از مخفف دوحرفی (برای مثال، 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. داده‌های رمزگذاری‌شده را بااستفاده از کدبندی hex یا 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

  • منطقه زمانی توکیو، ژاپن، که ۹ ساعت جلوتر از ساعت هماهنگ جهانی است و ساعت تابستانی را رعایت نمی‌کند: 2025-08-08T22:18:44.291+09:00

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

  • ‫seconds:‏ 1754683124

  • ‫nanos:‏ 291000000

رمزگذاری

الزامات کدگذاری بسته به اینکه داده‌های کاربر را رمزگذاری می‌کنید یا نه متفاوت است:

کدبندی گردش کارها

  • داده‌های کاربر رمزگذاری‌نشده: بایت‌های درهم‌سازی SHA-256 را بااستفاده از کدبندی شانزده‌شانزدهی (hex) یا کدبندی Base64 کدبندی کنید.

  • داده‌های رمزگذاری‌شده کاربر: اگر داده‌های کاربر را رمزگذاری می‌کنید، باید بایت‌های درهم‌سازی خام را قبل‌از رمزگذاری، با Base64 کدگذاری کنید. کدبندی شانزده‌شانزدهی برای درهم‌سازی پیش‌رمزگذاری پشتیبانی نمی‌شود. سپس می‌توانید متن رمزی حاصل را بااستفاده از کدبندی شانزده‌شانزدهی یا Base64 کدبندی کنید.

قبلی
پیکربندی مقصدها و سرایندها
بعدی
رمزگذاری داده‌های کاربر