Notification Payload — यह क्या है, JSON संरचना और पार्सिंग

Notification Payload क्या है

Notification Payload एक JSON ऑब्जेक्ट है जिसे सर्वर iOS डिवाइस पर डिलीवर के लिए APNS (Apple Push Notification Service) को भेजता है। पेलोड में वह सब डेटा होता है जिसकी सिस्टम को नोटिफिकेशन प्रदर्शित करने के लिए आवश्यकता होती है: शीर्षक, टेक्स्ट, ध्वनि, बेज़ और बैकग्रौंड प्रोसेसिंग के लिए मेटाडेटा। पेलोड संरचना 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 कुंजी: स्ट्रिंग और शब्दकोश प्रारूप

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 में सिस्टम प्रोसेसिंग के बाद प्राप्त पेलोड का पूरा शब्दकोश होता है। ऐप नोटिफिकेशन प्राप्त करने पर (अग्रभूमि में), नोटिफिकेशन पर टैप करने पर, साथ ही Service Extension और Content Extension में UNUserNotificationCenter डेलेगेट में पेलोड तक पहुंचता है। कस्टम डेटा निकालने और आगे की कार्रवाई निर्धारित करने के लिए सही पार्सिंग आवश्यक है।

नोटिफिकेशन पर टैप करने पर 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 या आकार सीमा से अधिक होने का संकेत देती है।