Notification Service Extension — wie die Push-Benachrichtigungsverarbeitung funktioniert

Was ist Notification Service Extension

Notification Service Extension ist eine App-Erweiterung in iOS, die eine eingehende Push-Benachrichtigung auf dem Gerät abfängt und es ermöglicht, ihren Inhalt zu ändern, bevor der Benutzer sie sieht. Dies ist der einzige Typ von Benachrichtigungserweiterung, der mit Inhalten und nicht mit der Anzeige arbeitet.

Der Hauptunterschied zur Notification Content Extension: Service Extension arbeitet vor der Anzeige der Benachrichtigung und kann Titel, Text, Sounddatei und Anhänge ändern. Content Extension arbeitet nach der Anzeige und verwaltet nur die visuelle Darstellung der fertigen Benachrichtigung. Diese beiden Erweiterungen können zusammenarbeiten: Service Extension lädt ein Bild herunter, und Content Extension zeigt es in einer benutzerdefinierten Oberfläche an.

Die Erweiterung wird automatisch beim Empfang einer Push-Benachrichtigung mit dem Attribut mutable-content:1 im aps-Wörterbuch aktiviert. iOS startet die Erweiterung im Hintergrund, übergibt ihr die ursprüngliche UNNotificationRequest und wartet auf eine modifizierte Version zur Anzeige.

Push-Benachrichtigungen spontan verarbeiten

UNNotificationServiceExtension erhält die vollständige UNNotificationRequest mit dem ursprünglichen Inhalt. Die Erweiterung kann beliebige Felder von UNNotificationContent ändern: title, subtitle, body, userInfo, attachments und sound. Die Änderungen werden angewendet, bevor die Benachrichtigung angezeigt wird.

Typische Nutzungsszenarien

Inhaltsentschlüsselung — wenn eine Push-Benachrichtigung eine verschlüsselte Nutzlast enthält, entschlüsselt die Erweiterung sie vor der Anzeige. Mediendownload — Anhängen eines Bildes oder Videos an die Benachrichtigung. Lokalisierung — Anpassung des Benachrichtigungstextes an die regionalen Einstellungen des Geräts. Datenanreicherung — Hinzufügen zusätzlicher Informationen aus dem lokalen Speicher oder Cache.

Laut Apple ist das häufigste Szenario in Apps das Herunterladen von Bildern für umfangreiche Medienbenachrichtigungen. Der Server sendet eine Bild-URL in der Nutzlast, die Erweiterung lädt sie in ein temporäres Verzeichnis herunter und erstellt ein UNNotificationAttachment, das das System in einer Standard- oder benutzerdefinierten Oberfläche anzeigt.

Text- und Titeländerung

Die Erweiterung kann den Benachrichtigungstext vollständig umschreiben, den Titel ersetzen oder einen Untertitel hinzufügen. Beispielsweise kann eine Messenger-App eine verschlüsselte Benachrichtigung erhalten, sie in der Erweiterung entschlüsseln und lesbaren Text anzeigen. Oder eine Nachrichten-App kann vor der Anzeige eine Nachrichtenkategorie zum Untertitel hinzufügen.

override func didReceive(
    _ request: UNNotificationRequest,
    withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
) {
    let content = request.content.mutableCopy()
        as! UNMutableNotificationContent
    if let imageURL = content.userInfo["media-url"]
        as? String {
        downloadAndAttach(imageURL: imageURL,
            content: content,
            handler: contentHandler)
    }
}

UNNotificationServiceExtension-Protokoll

UNNotificationServiceExtension ist die Basisklasse, von der Service Extension erbt. Die Klasse definiert zwei Lebenszyklusmethoden: didReceive(_:withContentHandler:) — die Hauptverarbeitungsmethode, und serviceExtensionTimeWillExpire() — den Timeout-Handler.

Methode didReceive:withContentHandler:

didReceive(_:withContentHandler:) wird beim Empfang einer Benachrichtigung aufgerufen. Die Erweiterung erhält eine UNNotificationRequest und einen contentHandler-Closure, der mit dem geänderten UNMutableNotificationContent aufgerufen werden muss. Die Erweiterung ist verpflichtet, contentHandler aufzurufen — wenn sie dies nicht tut, zeigt iOS nach Ablauf des Timeouts die ursprüngliche Benachrichtigung an.

Wichtig: Die Erweiterung kann jeweils nur eine Benachrichtigung verarbeiten. Wenn mehrere Benachrichtigungen gleichzeitig eingehen, erstellt iOS separate Erweiterungsinstanzen für jede. Ein globaler Zustand für die sequenzielle Verarbeitung kann nicht verwendet werden.

Methode serviceExtensionTimeWillExpire:

serviceExtensionTimeWillExpire() wird vom System aufgerufen, wenn die verbleibende Ausführungszeit abläuft. In dieser Methode müssen Sie sofort contentHandler mit dem Inhalt aufrufen, der zu diesem Zeitpunkt bereit ist — selbst wenn die Mediendatei noch nicht vollständig heruntergeladen wurde. Wenn Sie contentHandler in dieser Methode nicht aufrufen, zeigt iOS die ursprüngliche Benachrichtigung an.

Es wird empfohlen, in dieser Methode minimal akzeptablen Inhalt zu speichern — beispielsweise eine Benachrichtigung mit Text und Titel, aber ohne Bild, dessen Download nicht rechtzeitig abgeschlossen wurde.

Verschlüsselung und Medienanhänge

UNNotificationAttachment ist ein Objekt, das von der Erweiterung erstellt wird, um eine Mediendatei an die Benachrichtigung anzuhängen. Die Erweiterung lädt die Datei aus dem Netzwerk herunter, speichert sie in einem temporären Verzeichnis und erstellt ein UNNotificationAttachment mit Angabe des Inhaltstyps.

Erstellen eines Anhangs aus einer heruntergeladenen Datei

UNNotificationAttachment wird mit dem Initialisierer init(identifier:url:options:) erstellt. Die URL muss auf eine lokale Datei im für die Erweiterung zugänglichen temporären Verzeichnis verweisen. Nach der Erstellung wird der Anhang zum attachments-Array von UNMutableNotificationContent hinzugefügt.

Apple empfiehlt die Verwendung von URLSession mit Hintergrundkonfiguration zum Herunterladen — bei Verwendung der Standard-URLSession blockiert der Download den Thread und verbraucht Zeit vom 30-Sekunden-Limit. Die Hintergrund-URLSession setzt den Download auch nach Beendigung der Erweiterung fort, und das Ergebnis kann beim nächsten Start verwendet werden.

Entschlüsseln einer verschlüsselten Nutzlast

Wenn der Server eine verschlüsselte Benachrichtigung sendet, muss die Erweiterung die Nutzlast vor dem Aufruf von contentHandler entschlüsseln. Die Entschlüsselung umfasst in der Regel das Anfordern eines Schlüssels aus der Keychain oder App Group, das Entschlüsseln über CommonCrypto und das Ersetzen des body oder userInfo der Benachrichtigung. Bei einem Entschlüsselungsfehler sollten Sie contentHandler mit dem ursprünglichen Inhalt aufrufen — damit der Benutzer zumindest sieht, dass eine Benachrichtigung eingegangen ist, auch wenn sie nicht lesbar ist.

func downloadAndAttach(
    imageURL: String,
    content: UNMutableNotificationContent,
    handler: @escaping (UNNotificationContent) -> Void
) {
    let task = URLSession.shared.dataTask(with:
        URL(string: imageURL)!) { data, _, _ in
        let url = FileManager.default
            .temporaryDirectory
            .appendingPathComponent("image.jpg")
        try? data?.write(to: url)
        let attachment = try? UNNotificationAttachment(
            identifier: "image", url: url)
        content.attachments = [attachment].compactMap { $0 }
        handler(content)
    }
    task.resume()
}

Timeouts und Fallback-Mechanismen

Notification Service Extension arbeitet unter strengen zeitlichen Vorgaben. iOS weist eine feste Ausführungszeit zu — etwa 30 Sekunden ab der Aktivierung. Wenn die Erweiterung innerhalb dieser Zeit contentHandler nicht aufgerufen hat, beendet das System den Prozess zwangsweise und zeigt die ursprüngliche Benachrichtigung unverändert an.

Graceful-Degradation-Strategie

Es wird empfohlen, einen mehrstufigen Fallback zu implementieren: zuerst versuchen, Medien herunterzuladen, bei Erfolg contentHandler mit vollständigem Inhalt aufrufen; bei Misserfolg contentHandler mit Text, aber ohne Medien aufrufen; bei kritischem Fehler den ursprünglichen Inhalt übergeben. Dieser Ansatz stellt sicher, dass der Benutzer immer eine Benachrichtigung sieht und keinen leeren Bildschirm.

Laut Apple ist die häufigste Ursache für Timeouts das Herunterladen großer Mediendateien bei langsamer Verbindung. Um das Risiko zu verringern, wird empfohlen, die Bildgröße auf dem Server zu optimieren — Vorschaubilder bis zu 300 KB statt voller Auflösung zu senden. Vollformatige Bilder sollten beim Öffnen der App heruntergeladen werden.

Leistungsüberwachung

Um Timeouts und Fehler der Erweiterung zu verfolgen, können Sie os_log verwenden, um Diagnosemeldungen im Unified Logging System aufzuzeichnen. Obwohl die direkte Dateiprotokollierung in der Erweiterung schwierig ist, ermöglicht os_log eine Leistungsanalyse über die Console.app auf dem Entwicklergerät. Apple empfiehlt, bei jedem didReceive-Aufruf Metriken hinzuzufügen — Downloadzeit, Dateigröße, Operationsergebnis.

override func serviceExtensionTimeWillExpire() {
    let fallback = bestEffortContent as?
        UNMutableNotificationContent
        ?? request.content.mutableCopy()
        as! UNMutableNotificationContent
    contentHandler(fallback)
}