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) ফোকাস সিস্টেমকে একটি বিভাগের মধ্যে বিজ্ঞপ্তি রেঙ্ক করতে সাহায্য করে।

thread-id এর মাধ্যমে বিজ্ঞপ্তি গ্রুপিং

thread-id কীটি বিজ্ঞপ্তি কেন্দ্রে বিজ্ঞপ্তি গ্রুপিং করে। সকল বিজ্ঞপ্তি একই thread-id সহ একটি একক হিসাবে প্রদর্শিত হয় যা ব্যবহারকারী প্রাসারিত করতে পারে। এটি বিশেষ করে মেসেঞ্জারদের জন্য উপযোগী যেখানে এক সংস্পর্শের বার্তাগুলো একসাথে গ্রুপ করা হয়, বা অ্যাপগুলোর জন্য যা একই ধরনের অনেক বিজ্ঞপ্তি পাঠায়।

কাস্টম ফিল্ড এবং ডাটা স্থানান্তর

কাস্টম ফিল্ড হল aps অভিধানের বাইরে যেকোনো কী যা ডেভেলপার ডিভাইসে অতিরিক্ত ডাটা পার্থানোর জন্য যোগ করে। সরভার9 পেলোডের মূল 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 বা আকার সীমা অতিক্রমের ইঙ্গিত দেয়।