Notification Payload — این چیست، ساختار JSON و تجزیه

Notification Payload چیست

Notification Payload (پیلود اعلان) — یک شی JSON است که سرور برای تحویل به دستگاه iOS به APNS (Apple Push Notification Service) ارسال می‌کند. پیلود شامل تمام داده‌های لازم برای سیستم جهت نمایش اعلان است: عنوان، متن، صدا، badge و فراداده برای پردازش پس‌زمینه. ساختار پیلود به شدت توسط اپل تنظیم شده و شامل کلیدهای اجباری برای پردازش صحیح توسط سیستم است.

نقش پیلود در تحویل push

وقتی سرور یک اعلان push را از طریق HTTP/2 API APNS ارسال می‌کند، درخواست شامل هدرهای احراز هویت و بدنه JSON — پیلود است. APNS اعتبار پیلود را بررسی می‌کند: اگر JSON نامعتبر باشد یا از حد اندازه تجاوز کند، سرور اپل خطای 400 Bad Request را برمی‌گرداند. پس از اعتبارسنجی، APNS پیلود را به دستگاه تحویل می‌دهد، جایی که سیستم iOS آن را تجزیه کرده و تعیین می‌کند چگونه اعلان را پردازش کند — نمایش بنر، اجرای وظیفه پس‌زمینه یا پخش صدا.

تکامل فرمت پیلود

فرمت پیلود APNS از یک پیلود متنی ساده در iOS 2 به یک ساختار JSON چندجزئی در نسخه‌های مدرن تکامل یافته است. iOS 10 پشتیبانی از پیوست‌های رسانه‌ای را از طریق mutable-content به ارمغان آورد، iOS 12 گروه‌بندی اعلان‌ها را از طریق thread-id اضافه کرد، و iOS 15 supports-live-activities را برای Live Activities معرفی کرد. امروزه پیلود می‌تواند بسته به رفتار مورد نیاز اعلان تا ۱۵ کلید مختلف داشته باشد.

ساختار پیلود APNS: کلیدهای اجباری و اختیاری

شی ریشه پیلود شامل دیکشنری aps و فیلدهای سفارشی اختیاری در سطح بالایی است. دیکشنری aps تنها عنصر اجباری است، اما درون آن بسته به نوع اعلان ترکیبات مختلفی از کلیدها می‌تواند وجود داشته باشد: alert، badge، sound، content-available، mutable-content، interruption-level و غیره.

کلید alert: فرمت رشته‌ای و دیکشنری

کلید alert می‌تواند یک رشته ساده (که بدنه اعلان می‌شود) یا یک دیکشنری با فیلدهای title، subtitle، body باشد. فرمت دیکشنری امکان تنظیم عنوان و زیرعنوان را جدا از متن اصلی فراهم می‌کند. برای اعلان‌های محلی‌سازی شده از کلیدهای title-loc-key، title-loc-args، loc-key، loc-args استفاده می‌شود که به Localizable.strings برنامه ارجاع می‌دهند. این امکان ارسال پیلود بدون متن به زبان خاص را فراهم می‌کند — برنامه ترجمه را جایگزین می‌کند.

مدیریت قطع کردن: interruption-level و relevance-score

از iOS 15 به بعد، اپل مکانیزم Focus Mode را اضافه کرد که از توسعه‌دهنده می‌خواهد سطح قطع اعلان را مشخص کند. interruption-level مقادیر زیر را می‌پذیرد: passive (بدون صدا، بدون بیدار کردن صفحه)، active (رفتار استاندارد)، time-sensitive (از focus عبور می‌کند، نیاز به مجوز ویژه دارد) و critical (موقعیت‌های پزشکی/اضطراری). کلید relevance-score (0–1) به سیستم Focus کمک می‌کند اعلان‌ها را در یک دسته رتبه‌بندی کند.

گروه‌بندی اعلان‌ها از طریق thread-id

کلید thread-id اعلان‌ها را در Notification Center در گروه‌ها ترکیب می‌کند. همه اعلان‌ها با thread-id یکسان به صورت یک گروه نمایش داده می‌شوند که کاربر می‌تواند آن را باز کند. این به ویژه برای پیام‌رسان‌ها مفید است، جایی که پیام‌های یک مخاطب با هم گروه‌بندی می‌شوند، یا برای برنامه‌هایی که اعلان‌های زیادی از یک نوع ارسال می‌کنند.

فیلدهای سفارشی و انتقال داده

فیلدهای سفارشی — هر کلید خارج از دیکشنری aps است که توسعه‌دهنده برای انتقال داده‌های اضافی به دستگاه اضافه می‌کند. سرور آنها را در شی JSON ریشه پیلود قرار می‌دهد و برنامه آنها را از طریق userInfo در UNNotificationContent دریافت می‌کند. فیلدهای سفارشی نباید نام کلیدهای aps را تکرار کنند تا از تداخل در هنگام تجزیه جلوگیری شود.

محدودیت‌های داده‌های سفارشی

محدودیت اصلی — اندازه کل پیلود نباید از 4096 بایت تجاوز کند. فیلدهای سفارشی برای این حد با کلیدهای اجباری aps رقابت می‌کنند، بنابراین مهم است که اندازه داده‌های ارسالی را به حداقل برسانید. از نام‌های کوتاه برای کلیدها استفاده کنید (مثلاً «uid» به جای «user-id»)، از ساختارهای JSON بزرگ خودداری کنید و فقط شناسه‌ها را ارسال کنید، نه اشیاء کامل داده.

امنیت و اعتبارسنجی فیلدهای سفارشی

فیلدهای سفارشی از سرور می‌آیند و بدون بررسی نباید به آنها اعتماد کرد. همیشه اعتبارسنجی کنید انواع و مقادیر فیلدهای سفارشی را در هنگام تجزیه: وجود کلید را از طریق optional binding بررسی کنید، به نوع مورد انتظار با as? String/Int/Dictionary تبدیل کنید و حالت عدم وجود مقدار را مدیریت کنید. هرگز از force unwrap (!) برای داده‌های پیلود استفاده نکنید — سرور ممکن است داده نامعتبر ارسال کند و برنامه crash کند.

{
    "aps": {
        "alert": {
            "title": "پیام جدید",
            "body": "سلام! حالت چطوره؟"
        },
        "badge": 5,
        "sound": "default",
        "category": "message",
        "thread-id": "chat_4521",
        "mutable-content": 1
    },
    "sender-id": "user_789",
    "chat-id": "chat_4521",
    "message-type": "text",
    "image-url": "https://cdn.example.com/img.jpg"
}

توصیه‌هایی برای نام‌گذاری فیلدهای سفارشی

از یک سبک نام‌گذاری یکپارچه برای فیلدهای سفارشی در تمام پیلودهای پروژه استفاده کنید. kebab-case (message-type) یا camelCase (messageType) — هر دو رویکرد قابل قبول هستند، اما مهم است که در چارچوب پروژه به یکی پایبند باشید. از نام‌های طولانی خودداری کنید: «uid» به جای «user-identifier»، «img» به جای «profile-image-url». هر کاراکتر در نام کلید یک بایت از حد 4096 است.

نمونه پیلودها برای انواع مختلف اعلان

سناریوهای مختلف اعلان‌های push به ترکیبات مختلفی از کلیدها در پیلود نیاز دارند. بیایید چند نمونه معمولی را بررسی کنیم: اعلان متنی ساده، اعلان با محلی‌سازی، Silent Push و Rich Notification با پیوست رسانه‌ای.

اعلان متنی ساده

پیلود پایه با متن و صدا — حداقل پیکربندی برای نمایش اعلان به کاربر. Alert به عنوان رشته پیام کوتاهی می‌دهد، sound default صدای سیستم استاندارد را پخش می‌کند. Badge اختیاری است و شمارنده را روی آیکون تنظیم می‌کند. category و thread-id برای گروه‌بندی و تعامل اضافه می‌شوند.

{
    "aps": {
        "alert": "یادآوری: جلسه ۱۵ دقیقه دیگر",
        "badge": 3,
        "sound": "default"
    }
}

اعلان با محلی‌سازی

برای ارسال به دستگاه‌هایی با زبان‌های مختلف به جای متن ثابت از کلیدهای محلی‌سازی استفاده کنید. title-loc-key به کلیدی در Localizable.strings برنامه ارجاع می‌دهد و title-loc-args آرگومان‌ها را جایگزین می‌کند. این امکان ارسال یک پیلود به همه دستگاه‌ها را فراهم می‌کند و برنامه خود متن را به زبان مناسب نمایش می‌دهد.

{
    "aps": {
        "alert": {
            "title-loc-key": "NEW_MESSAGE_TITLE",
            "title-loc-args": ["آنا"],
            "loc-key": "NEW_MESSAGE_BODY",
            "loc-args": ["سلام!"]
        },
        "sound": "message.caf"
    }
}

Silent Push با همگام‌سازی پس‌زمینه

برای همگام‌سازی پس‌زمینه بدون نمایش اعلان از content-available: 1 و عدم وجود alert استفاده می‌شود. فیلدهای سفارشی نوع عملیات و داده‌های پردازش را مشخص می‌کنند. سیستم برنامه را در پس‌زمینه فعال می‌کند، didReceiveRemoteNotification را با fetchCompletionHandler فراخوانی می‌کند و برنامه همگام‌سازی را انجام می‌دهد.

{
    "aps": {
        "content-available": 1
    },
    "sync-type": "invalidate-cache",
    "timestamp": "2026-07-03T12:00:00Z"
}

Rich Notification با تصویر

برای نمایش پیوست رسانه‌ای، mutable-content: 1 برای فعال‌سازی Service Extension و URL تصویر در فیلد سفارشی لازم است. mutable-content: 1 به سیستم علامت می‌دهد UNNotificationServiceExtension را راه‌اندازی کند که تصویر را از URL دانلود کرده و به عنوان UNNotificationAttachment اضافه می‌کند. category به دسته ثبت‌شده برای نمایش دکمه‌های اقدام اشاره می‌کند.

{
    "aps": {
        "alert": {
            "title": "محصول جدید",
            "body": "مجموعه جدید را ببینید"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

پردازش و تجزیه پیلود در برنامه

UNNotificationContent.userInfo شامل دیکشنری کامل پیلود دریافت‌شده پس از پردازش توسط سیستم است. برنامه در delegate UNUserNotificationCenter هنگام دریافت اعلان (در پیش‌زمینه)، هنگام کلیک روی اعلان، و همچنین در Service Extension و Content Extension به پیلود دسترسی دارد. تجزیه صحیح برای استخراج داده‌های سفارشی و تعیین اقدامات بعدی ضروری است.

تجزیه در AppDelegate هنگام کلیک روی اعلان

وقتی کاربر روی اعلان کلیک می‌کند، سیستم متد didReceive response را در UNUserNotificationCenterDelegate فراخوانی می‌کند. در response.notification.request.content.userInfo پیلود کامل موجود است. توسعه‌دهنده فیلدهای سفارشی را استخراج می‌کند، نوع اقدام را تعیین می‌کند (مثلاً باز کردن چت، رفتن به محصول) و ناوبری مربوطه را در برنامه فراخوانی می‌کند.

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    let userInfo = response.notification
        .request.content.userInfo

    guard let chatId = userInfo["chat-id"] as? String
    else {
        completionHandler()
        return
    }

    let messageType = userInfo["message-type"]
        as? String ?? "text"

    NavigationRouter.shared.navigate(
        to: .chat(chatId: chatId,
                  messageType: messageType))
    completionHandler()
}

اعتبارسنجی پیلود در Service Extension

Service Extension پیلود را قبل از نمایش اعلان دریافت می‌کند و می‌تواند آن را تغییر دهد. اعتبارسنجی پیلود — اولین گام در didReceive: وجود فیلدهای سفارشی اجباری، صحت URL برای پیوست‌ها و نوع داده را بررسی کنید. اگر پیلود نامعتبر است، فوراً completion handler را با محتوای اصلی فراخوانی کنید، بدون اتلاف وقت برای پردازش بی‌فایده.

ثبت و نظارت بر پیلودها

برای اشکال‌زدایی اعلان‌های push در تولید از ثبت ساختاریافته پیلودها استفاده کنید. OSLog امکان ثبت پیلود با دسته «notifications» و سطح debug را فراهم می‌کند. در سمت سرور، پاسخ‌های APNS را ردیابی کنید: پاسخ موفق شامل apns-id برای تطبیق با پیلود ارسالی است و خطای 400 نشان‌دهنده JSON نامعتبر یا تجاوز از اندازه است.