Notification Payload — τι είναι, JSON δομή και ανάλυση

Τι είναι το Notification Payload

Notification Payload (payload ειδοποίησης) — είναι ένα αντικείμενο JSON που στέλνει ο διακομιστής στο APNS (Apple Push Notification Service) για παράδοση σε μια συσκευή iOS. Το payload περιέχει όλα τα δεδομένα που χρειάζεται το σύστημα για να εμφανίσει την ειδοποίηση: τίτλο, κείμενο, ήχο, badge και μεταδεδομένα για επεξεργασία στο παρασκήνιο. Η δομή του payload ρυθμίζεται αυστηρά από την Apple και περιλαμβάνει υποχρεωτικά κλειδιά για σωστή επεξεργασία από το σύστημα.

Ρόλος του payload στην παράδοση push

Όταν ο διακομιστής στέλνει μια push ειδοποίηση μέσω του HTTP/2 API APNS, το αίτημα περιέχει κεφαλίδες εξουσιοδότησης και σώμα JSON — το payload. Το APNS ελέγχει την εγκυρότητα του payload: εάν το JSON είναι λανθασμένο ή υπερβαίνει το όριο μεγέθους, ο διακομιστής της Apple επιστρέφει σφάλμα 400 Bad Request. Μετά την επικύρωση, το APNS παραδίδει το payload στη συσκευή, όπου το σύστημα iOS το αναλύει και καθορίζει πώς να επεξεργαστεί την ειδοποίηση — να εμφανίσει ένα banner, να εκτελέσει μια εργασία παρασκηνίου ή να αναπαραγάγει έναν ήχο.

Εξέλιξη της μορφής payload

Η μορφή payload APNS εξελίχθηκε από ένα απλό κειμενικό payload στο iOS 2 σε μια πολυσυστατική δομή JSON στις σύγχρονες εκδόσεις. Το iOS 10 έφερε υποστήριξη για συνημμένα πολυμέσων μέσω mutable-content, το iOS 12 πρόσθεσε ομαδοποίηση ειδοποιήσεων μέσω thread-id, και το iOS 15 εισήγαγε το supports-live-activities για Live Activities. Σήμερα, το payload μπορεί να περιέχει έως 15 διαφορετικά κλειδιά ανάλογα με την επιθυμητή συμπεριφορά της ειδοποίησης.

Δομή APNS payload: υποχρεωτικά και προαιρετικά κλειδιά

Το ριζικό αντικείμενο του payload περιέχει το λεξικό 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 της εφαρμογής. Αυτό επιτρέπει την αποστολή payload χωρίς κείμενο σε συγκεκριμένη γλώσσα — η εφαρμογή αντικαθιστά τη μετάφραση.

Διαχείριση διακοπών: interruption-level και relevance-score

Από το iOS 15, η Apple πρόσθεσε τον μηχανισμό Focus Mode, ο οποίος απαιτεί από τον προγραμματιστή να καθορίσει το επίπεδο διακοπής της ειδοποίησης. interruption-level δέχεται τιμές: passive (χωρίς ήχο, χωρίς αφύπνιση οθόνης), active (τυπική συμπεριφορά), time-sensitive (διαπερνά την εστίαση, απαιτεί special entitlement) και critical (ιατρικές/επείγουσες καταστάσεις). Το κλειδί relevance-score (0–1) βοηθά το σύστημα Focus να κατατάσσει ειδοποιήσεις εντός μιας κατηγορίας.

Ομαδοποίηση ειδοποιήσεων μέσω thread-id

Το κλειδί thread-id συνδυάζει ειδοποιήσεις σε ομάδες στο Notification Center. Όλες οι ειδοποιήσεις με το ίδιο thread-id εμφανίζονται ως μία ομάδα που ο χρήστης μπορεί να αναπτύξει. Αυτό είναι ιδιαίτερα χρήσιμο για εφαρμογές ανταλλαγής μηνυμάτων, όπου τα μηνύματα από μια επαφή ομαδοποιούνται μαζί, ή για εφαρμογές που στέλνουν πολλές ειδοποιήσεις του ίδιου τύπου.

Προσαρμοσμένα πεδία και μετάδοση δεδομένων

Προσαρμοσμένα πεδία — είναι τυχόν κλειδιά εκτός του λεξικού aps που προσθέτει ο προγραμματιστής για μετάδοση πρόσθετων δεδομένων στη συσκευή. Ο διακομιστής τα συμπεριλαμβάνει στο ριζικό αντικείμενο JSON του payload, και η εφαρμογή τα λαμβάνει μέσω userInfo στο UNNotificationContent. Τα προσαρμοσμένα πεδία δεν πρέπει να αντιγράφουν τα ονόματα κλειδιών από το aps για αποφυγή συγκρούσεων κατά την ανάλυση.

Περιορισμοί στα προσαρμοσμένα δεδομένα

Ο κύριος περιορισμός — το συνολικό μέγεθος του payload δεν πρέπει να υπερβαίνει τα 4096 byte. Τα προσαρμοσμένα πεδία ανταγωνίζονται για αυτό το όριο με τα υποχρεωτικά κλειδιά aps, επομένως είναι σημαντικό να ελαχιστοποιείτε το μέγεθος των μεταδιδόμενων δεδομένων. Χρησιμοποιήστε σύντομα ονόματα κλειδιών (π.χ. uid αντί για user-id), αποφύγετε μεγάλες δομές JSON και μεταδώστε μόνο αναγνωριστικά, όχι πλήρη αντικείμενα δεδομένων.

Ασφάλεια και επικύρωση προσαρμοσμένων πεδίων

Τα προσαρμοσμένα πεδία προέρχονται από τον διακομιστή και δεν πρέπει να τα εμπιστεύεστε χωρίς έλεγχο. Πάντα να επικυρώνετε τους τύπους και τις τιμές των προσαρμοσμένων πεδίων κατά την ανάλυση: ελέγχετε την ύπαρξη του κλειδιού μέσω optional binding, μετατρέπετε στον αναμενόμενο τύπο με as? String/Int/Dictionary και χειρίζεστε την περίπτωση απουσίας τιμής. Ποτέ μην χρησιμοποιείτε force unwrap (!) για δεδομένα από το payload — ο διακομιστής μπορεί να στείλει λανθασμένα δεδομένα και η εφαρμογή θα καταρρεύσει.

{
    "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"
}

Συστάσεις για την ονομασία προσαρμοσμένων πεδίων

Χρησιμοποιήστε ενιαίο στυλ ονομασίας για τα προσαρμοσμένα πεδία σε όλα τα payload του έργου. kebab-case (message-type) ή camelCase (messageType) — και οι δύο προσεγγίσεις είναι αποδεκτές, αλλά είναι σημαντικό να ακολουθείτε μία εντός του έργου. Αποφύγετε μακροσκελή ονόματα: uid αντί για user-identifier, img αντί για profile-image-url. Κάθε χαρακτήρας στο όνομα κλειδιού είναι ένα byte από το όριο των 4096.

Παραδείγματα payload για διαφορετικούς τύπους ειδοποιήσεων

Διαφορετικά σενάρια push ειδοποιήσεων απαιτούν διαφορετικούς συνδυασμούς κλειδιών στο payload. Ας εξετάσουμε μερικά τυπικά παραδείγματα: απλή κειμενική ειδοποίηση, ειδοποίηση με τοπικοποίηση, Silent Push και Rich Notification με συνημμένο πολυμέσων.

Απλή κειμενική ειδοποίηση

Βασικό payload με κείμενο και ήχο — ελάχιστη διαμόρφωση για εμφάνιση ειδοποίησης στον χρήστη. Alert ως συμβολοσειρά δίνει ένα σύντομο μήνυμα, το sound default αναπαράγει τον τυπικό ήχο συστήματος. Το badge είναι προαιρετικό και ορίζει μετρητή στο εικονίδιο. Το category και thread-id προστίθενται για ομαδοποίηση και διαδραστικότητα.

{
    "aps": {
        "alert": "Υπενθύμιση: συνάντηση σε 15 λεπτά",
        "badge": 3,
        "sound": "default"
    }
}

Ειδοποίηση με τοπικοποίηση

Για αποστολή σε συσκευές με διαφορετικές γλώσσες, χρησιμοποιήστε κλειδιά τοπικοποίησης αντί για σταθερό κείμενο. title-loc-key αναφέρεται σε ένα κλειδί στο Localizable.strings της εφαρμογής, και το title-loc-args αντικαθιστά τα ορίσματα. Αυτό επιτρέπει την αποστολή ενός payload σε όλες τις συσκευές, και η εφαρμογή εμφανίζει το κείμενο στην κατάλληλη γλώσσα.

{
    "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"
}

Επεξεργασία και ανάλυση payload στην εφαρμογή

UNNotificationContent.userInfo περιέχει το πλήρες λεξικό του ληφθέντος payload μετά την επεξεργασία από το σύστημα. Η εφαρμογή έχει πρόσβαση στο payload στον delegate του UNUserNotificationCenter κατά τη λήψη της ειδοποίησης (στο προσκήνιο), κατά το πάτημα της ειδοποίησης, καθώς και στο Service Extension και Content Extension. Η σωστή ανάλυση είναι υποχρεωτική για την εξαγωγή προσαρμοσμένων δεδομένων και τον καθορισμό περαιτέρω ενεργειών.

Ανάλυση στο AppDelegate κατά το πάτημα ειδοποίησης

Όταν ο χρήστης πατάει μια ειδοποίηση, το σύστημα καλεί τη μέθοδο didReceive response στο UNUserNotificationCenterDelegate. Στο response.notification.request.content.userInfo βρίσκεται το πλήρες payload. Ο προγραμματιστής εξάγει τα προσαρμοσμένα πεδία, καθορίζει τον τύπο ενέργειας (π.χ. άνοιγμα συνομιλίας, μετάβαση σε προϊόν) και καλεί την αντίστοιχη πλοήγηση στην εφαρμογή.

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()
}

Επικύρωση payload στο Service Extension

Το Service Extension λαμβάνει το payload πριν από την εμφάνιση της ειδοποίησης και μπορεί να το τροποποιήσει. Η επικύρωση payload — το πρώτο βήμα στο didReceive: ελέγξτε την ύπαρξη υποχρεωτικών προσαρμοσμένων πεδίων, την ορθότητα του URL για συνημμένα και τον τύπο δεδομένων. Εάν το payload δεν είναι έγκυρο, καλέστε αμέσως το completion handler με το αρχικό περιεχόμενο, χωρίς να χάνετε χρόνο σε άχρηστη επεξεργασία.

Καταγραφή και παρακολούθηση payload

Για εντοπισμό σφαλμάτων push ειδοποιήσεων στην παραγωγή, χρησιμοποιήστε δομημένη καταγραφή payload. OSLog επιτρέπει την καταγραφή payload με κατηγορία notifications και επίπεδο debug. Από την πλευρά του διακομιστή, παρακολουθείτε τις απαντήσεις APNS: μια επιτυχημένη απάντηση περιέχει apns-id για αντιστοίχιση με το σταλμένο payload, και ένα σφάλμα 400 υποδεικνύει μη έγκυρο JSON ή υπέρβαση μεγέθους.