Notification Payload — یہ کیا ہے، JSON ساخت اور پارسنگ

Notification Payload کیا ہے

Notification Payload ایک JSON آبیکٹ ہے جو سرور APNS (Apple Push Notification Service) کو iOS آلے پر ترسیل کے لیے بھیجتا ہے۔ پیلوڈ میں وہ سارا ڈیٹا ہوتا ہے جو سیسٹم کو نوٹفکیشن دیکھانے کے لیے چاہیے: عنوان، متن، آواز، بیج اور پس منظر پروسیسنگ کے لیے میٹا ڈیٹا۔ پیلوڈ کی ساخت Apple سختی سے منظم کرتا ہے اور سیسٹم کے ذریعے درست پروسیسنگ کے لیے لازمی کلیزی شامل کرتا ہے۔

Push ترسیل میں پیلوڈ کا کردار

جب سرور APNS HTTP/2 API کے ذریعے push نوٹفکیشن بھیجتا ہے، درخواست میں اختیار کے هیڈر اور ایک JSON باڈی — پیلوڈ ہوتا ہے۔ APNS پیلوڈ کی تصدیق کرتا ہے: اگر JSON غیر موزوں ہے یا سائز کی حد سے تجاوز کرتا ہے، تو Apple سرور 400 Bad Request خرابی واپس کرتا ہے۔ تصدیق کے بعد، APNS پیلوڈ کو آلے پر پہنچاتا ہے، جہاں iOS اسے پارس کرتا ہے اور نوٹفکیشن کے ساتھ کیسے نمٹنا ہے اس کا تعین کرتا ہے — ایک بینر دیکھانا، ایک پس منظر کا کام چلانا یا آواز چلانا۔

پیلوڈ کی شکل کا ارتقاء

APNS پیلوڈ کی شکل iOS 2 میں ایک سادہ متن پیلوڈ سے جدید ورژن میں ایک کثیر اجزائی JSON ساخت میں ترقی کرگے۔ iOS 10 نے mutable-content کے ذریعے میڈیا منسلقات کی حمایت متعارف کرائی، iOS 12 نے thread-id کے ذریعے نوٹفکیشن گروپنگ کا اضافہ کیا، اور iOS 15 نے Live Activities کے لیے supports-live-activities متعارف کرائی۔ آج، ایک پیلوڈ منصوبہ نوٹفکیشن رویہ کے اعتماد سے 15 تک مختلف کلیزی شامل کر سکتا ہے۔

APNS پیلوڈ کا چطہ: لازمی اور اختیاری کلیزی

جڑ آبیکٹ میں ایک aps لغت اور اوپر لیول پر اختیاری کسٹم فیلڈز ہوتے ہیں۔ aps لغت واحد لازمی عنصر ہے، لیکن اس کے اندر نوٹفکیشن کی قسم کے اعتماد سے کلیزی کے مختلف اجتماع موجود ہو سکتے ہیں: alert, badge, sound, content-available, mutable-content, interruption-level اور دیگر۔

alert کلیزی: String اور Dictionary کی شکل

alert کلیزی ایک سادہ سترنگ (جو نوٹفکیشن کا متن بن جاتی ہے) یا title, subtitle اور body فیلڈ کے ساتھ ایک لغت ہو سکتی ہے۔ لغت کی شکل اہم متن سے علاوہ عنوان اور ذیلی عنوان مقرر کرنے کی اجازت دیتی ہے۔ مقامی نوٹفکیشن کے لیے، title-loc-key, title-loc-args, loc-key اور loc-args کلیزی استعمال ہوتی ہیں جو ایپ کے Localizable.strings کا حوالہ دیتی ہیں۔ یہ ایک مخصوص زبان میں متن کے بغیر پیلوڈ بھیجنے کی اجازت دیتا ہے — ایپ ترجمہ کو بدل دیتا ہے۔

رکاوٹ کا نظام: interruption-level اور relevance-score

iOS 15 سے شروع کرتے ہوئے، Apple نے فوکس موڈ کا سیسٹم متعارف کرایا، جسے لیے ڈیولپر کو نوٹفکیشن کی رکاوٹ کی سطح متعین کرنے کی ضرورت ہے۔ interruption-level درج ذیل قدریتیں قبول کرتا ہے: passive (کوئی آواز نہیں، سکرین جاگری، نہیں)، active (معمولی رویہ)، time-sensitive (فوکس کو چیرتا ہے، خاص اختیار درکار ہے) اور critical (طبی/ہنگامی حالات)۔ relevance-score (0–1) کلیزی Focus سیسٹم کو ایک زمرے کے اندر نوٹفکیشن کو درجہ دےنے میں مدد کرتی ہے۔

thread-id کے ذریعے نوٹفکیشن گروپنگ

thread-id کلیزی نوٹفکیشن سینٹر میں نوٹفکیشن کو گروپ کرتی ہے۔ ایک ہی thread-id کے ساتھ تمام نوٹفکیشن ایک واحد گروپ کے طور پر دیکھائے جاتے ہیں جسے صاحب استعمال پھیلا سکتا ہے۔ یہ خاص طور پر میسنجرز کے لیے مفید ہے جہاں ایک رابطے کے پیغام ایک ساتھ گروپ کیئے جاتے ہیں، یا ایسے ایپ کے لیے جو ایک ہی قسم کے بہت سے نوٹفکیشن بھیجتے ہیں۔

کسٹم فیلڈز اور ڈیٹا منتقلی

کسٹم فیلڈز aps لغت کے باہر کوئی بھی کلیزی ہیں جو ڈیولپر آلے پر اضافی ڈیٹا منتقل کرنے کے لیے شامل کرتا ہے۔ سرور انہیں پیلوڈ کے جڑ JSON آبیکٹ میں شامل کرتا ہے، اور ایپ UNNotificationContent میں userInfo کے ذریعے انہیں حاصل کرتا ہے۔ کسٹم فیلڈز کو aps کے کلیزی ناموں کی نقل نہیں کرنی چاہئے تاکہ پارسنگ کے دوران تصادم سے بچا جا سکے۔

کسٹم ڈیٹا کی پابندیاں

اہم پابندی یہ ہے کہ کل پیلوڈ کا سائز 4096 بائٹ سے زیادہ نہیں ہونا چاہئے۔ کسٹم فیلڈز اس حد کے لیے لازمی aps کلیزی سے مقابلہ کرتے ہیں، اس لیے منتقل کردہ ڈیٹا کے سائز کو کم سے کم رکھنا اہم ہے۔ چھوٹے کلیزی نام استعمال کریں (مثال کے طور پر، “uid” “user-id” کے بجائے)، بڑے JSON چطہ سے بچیں اور مکمل ڈیٹا آبیکٹ کے بجائے صرف شناختی ترتیبات بھیجیں۔

کسٹم فیلڈز کی حفاظت اور تصدیق

کسٹم فیلڈز سرور سے آتے ہیں اور بغیر تصدیق کے ان پر بھروسہ نہیں کرنا چاہئے۔ پارسنگ کے دوران ہمیشہ تصدیق کریں کسٹم فیلڈز کی اقسام اور قدرتیں: اختیاری باندنگ کے ذریعے کلیزی کی موجودگی چیک کریں، as? String/Int/Dictionary کا استعمال کرکے متوقعہ قسم میں تبدیل کریں اور قدرت کی غیرحازگی کی ضد کریں۔ پیلوڈ سے ڈیٹا کے لیے کبھی force unwrap (!) کا استعمال نہ کریں — سرور غیر موزوں ڈیٹا بھیج سکتا ہے، جس سے ایپ کریش ہو سکتا ہے۔

{
    "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 نوٹفکیشن کے لیے پیلوڈ میں کلیزی کے مختلف اجتماع کی ضرورت ہوتی ہے۔ آئیے کچھ معیاری مثالیں دیکھیں: ایک سادہ متن نوٹفکیشن، ایک مقامی نوٹفکیشن، ایک خاموش push اور ایک میڈیا منسلق کے ساتھ ایک ریچ نوٹفکیشن۔

سادہ متن نوٹفکیشن

متن اور آواز کے ساتھ ایک بنیادی پیلوڈ — صاحب استعمال کو نوٹفکیشن دیکھانے کے لیے کم از کم ترتیب۔ سترنگ کے طور پر Alert ایک مختصر پیغام فراہم کرتا ہے، sound default معمولی سیسٹم کی آواز چلاتا ہے۔ Badge اختیاری ہے اور ایپ آئیکن پر کاؤنٹر مقرر کرتا ہے۔ category اور thread-id گروپنگ اور انٹریکٹیویٹی کے لیے شامل کیءے جاتے ہیں۔

{
    "aps": {
        "alert": "یاد دھانی: 15 منٹ میں میٹنگ",
        "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"
    }
}

پس منظر مطابقت کے ساتھ خاموش push

نوٹفکیشن دیکھائے بغیر پس منظر مطابقت کے لیے، alert کے بغیر content-available: 1 استعمال کریں۔ کسٹم فیلڈز پروسیسنگ کے لیے آپریشن کی قسم اور ڈیٹا متعین کرتے ہیں۔ سیسٹم پس منظر میں ایپ کو چالو کرتا ہے، fetchCompletionHandler کے ساتھ didReceiveRemoteNotification کو کال کرتا ہے، اور ایپ مطابقت کرتا ہے۔

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

تصویر کے ساتھ ریچ نوٹفکیشن

ایک میڈیا منسلق دیکھانے کے لیے، Service Extension چالو کرنے کے لیے mutable-content: 1 اور ایک کسٹم فیلڈ میں ایک تصویر کا 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 میں سیسٹم کے پروسیسنگ کے بعد موصول کردہ پیلوڈ کی مکمل لغت ہوتی ہے۔ ایپ UNUserNotificationCenter ڈیلیگیٹ میں نوٹفکیشن موصول کرنے پر (پیش منظر میں)، نوٹفکیشن پر ٹیپ کرنے پر، اور Service Extension اور Content Extension میں پیلوڈ تک رسائی حاصل کرتا ہے۔ کسٹم ڈیٹا نکالنے اور اگلی کاروائی کا تعین کرنے کے لیے درست پارسنگ ضروری ہے۔

نوٹفکیشن پر ٹیپ کرنے پر AppDelegate میں پارسنگ

جب صاحب استعمال ایک نوٹفکیشن پر ٹیپ کرتا ہے، سیسٹم UNUserNotificationCenterDelegate میں didReceive response کا طریقہ کال کرتا ہے۔ 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” زمرے کے ساتھ پیلوڈ کو لاگ کرنے کی اجازت دیتا ہے۔ سرور کی جانب سے، APNS جوابات کی نگرانی کریں: ایک کامیاب جواب میں بھیجے گئے پیلوڈ سے ملان کے لیے apns-id ہوتا ہے، جبکہ 400 خرابی غیر موزوں JSON یا سائز کی حد سے تجاوز کی نشاندہی کرتی ہے۔