Notification Service Extension — hoe meldingsverwerking werkt

Wat is Notification Service Extension

Notification Service Extension is een app-extensie in iOS die een inkomende pushmelding aan de apparaatzijde onderschept en de inhoud ervan kan wijzigen voordat de gebruiker deze ziet. Dit is het enige type meldingsextensie dat werkt met inhoud, niet met weergave.

Het belangrijkste verschil met Notification Content Extension: Service Extension werkt vóór het tonen van de melding en kan de titel, body, geluidsbestand en bijlagen wijzigen. Content Extension werkt na het tonen en beheert alleen de visuele weergave van de voltooide melding. Deze twee extensies kunnen samenwerken: Service Extension downloadt een afbeelding en Content Extension toont deze in een aangepaste interface.

De extensie wordt automatisch geactiveerd bij het ontvangen van een pushmelding met het attribuut mutable-content:1 in het aps-woordenboek. iOS start de extensie op de achtergrond, geeft de originele UNNotificationRequest door en wacht op de gewijzigde versie voor weergave.

Pushmeldingen direct verwerken

UNNotificationServiceExtension ontvangt de volledige UNNotificationRequest met de originele inhoud. De extensie kan alle velden van UNNotificationContent wijzigen: title, subtitle, body, userInfo, attachments en sound. Wijzigingen worden toegepast voordat de melding wordt getoond.

Typische gebruiksscenario's

Inhoud ontsleutelen — als de pushmelding versleutelde payload bevat, ontsleutelt de extensie deze vóór weergave. Media downloaden — een afbeelding of video aan de melding toevoegen. Lokalisatie — de meldingstekst aanpassen aan de regionale instellingen van het apparaat. Gegevens verrijken — extra informatie uit lokale opslag of cache toevoegen.

Volgens Apple is het meest voorkomende scenario onder apps het downloaden van afbeeldingen voor rijke mediameldingen. De server stuurt een afbeeldings-URL in de payload, de extensie downloadt deze naar een tijdelijke map en maakt UNNotificationAttachment aan, die het systeem weergeeft in de standaard of aangepaste interface.

Tekst en titel wijzigen

De extensie kan de tekst van de melding volledig herschrijven, de titel vervangen of een subtitle toevoegen. Een berichtenapp kan bijvoorbeeld een versleutelde melding ontvangen, deze in de extensie ontsleutelen en leesbare tekst tonen. Of een nieuwsapp kan de nieuwscategorie aan de subtitel toevoegen vóór weergave.

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

Protocol UNNotificationServiceExtension

UNNotificationServiceExtension — de basisklasse waarvan Service Extension overerft. De klasse definieert twee levenscyclusmethoden: didReceive(_:withContentHandler:) — de belangrijkste verwerkingsmethode, en serviceExtensionTimeWillExpire() — de handler voor tijdsverloop.

Methode didReceive:withContentHandler:

didReceive(_:withContentHandler:) wordt aangeroepen bij ontvangst van een melding. De extensie ontvangt UNNotificationRequest en een contentHandler-closure die moet worden aangeroepen met de gewijzigde UNMutableNotificationContent. De extensie is verplicht contentHandler aan te roepen — als dit niet gebeurt, toont iOS de originele melding na het verstrijken van de time-out.

Belangrijk: de extensie kan slechts één melding tegelijk verwerken. Als er meerdere meldingen tegelijk binnenkomen, maakt iOS afzonderlijke instanties van de extensie voor elke melding. Globale toestand voor sequentiële verwerking kan niet worden gebruikt.

Methode serviceExtensionTimeWillExpire:

serviceExtensionTimeWillExpire() wordt door het systeem aangeroepen wanneer de resterende uitvoeringstijd bijna is verstreken. In deze methode moet onmiddellijk contentHandler worden aangeroepen met de inhoud die op dat moment gereed is — zelfs als het mediabestand nog niet is gedownload. Als contentHandler in deze methode niet wordt aangeroepen, toont iOS de originele melding.

Het wordt aanbevolen om in deze methode minimaal aanvaardbare inhoud te bewaren — bijvoorbeeld een melding met tekst en titel, maar zonder de afbeelding waarvan de download niet op tijd is voltooid.

Versleuteling en mediabijlagen

UNNotificationAttachment — een object dat door de extensie wordt gemaakt om een mediabestand aan de melding toe te voegen. De extensie downloadt het bestand uit het netwerk, slaat het op in een tijdelijke map en maakt UNNotificationAttachment met specificatie van het inhoudstype.

Een bijlage maken van een gedownload bestand

UNNotificationAttachment wordt gemaakt met behulp van de initialisator init(identifier:url:options:). De URL moet verwijzen naar een lokaal bestand in de tijdelijke map die toegankelijk is voor de extensie. Na het maken wordt de bijlage toegevoegd aan de attachments-array van UNMutableNotificationContent.

Apple raadt het gebruik van URLSession met achtergrondconfiguratie aan voor downloads — bij gebruik van de standaard URLSession blokkeert de download de thread en verbruikt tijd van de 30-secondenlimiet. URLSession op de achtergrond gaat door met downloaden, zelfs nadat de extensie is beëindigd, en het resultaat kan bij de volgende start worden gebruikt.

Versleutelde payload ontsleutelen

Als de server een versleutelde melding verzendt, moet de extensie de payload ontsleutelen voordat contentHandler wordt aangeroepen. Ontsleuteling omvat meestal het opvragen van een sleutel uit Keychain of App Group, decodering via CommonCrypto en het vervangen van de body of userInfo van de melding. Bij een ontsleutelingsfout moet contentHandler worden aangeroepen met de originele inhoud — zodat de gebruiker tenminste ziet dat de melding is aangekomen, zelfs als deze onleesbaar is.

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

Time-outs en fallback-mechanismen

Notification Service Extension werkt binnen strikte tijdslimieten. iOS kent een vaste uitvoeringstijd toe — ongeveer 30 seconden vanaf het moment van activering. Als de extensie contentHandler niet binnen deze tijd aanroept, beëindigt het systeem het proces geforceerd en toont de originele melding zonder wijzigingen.

Graceful degradation-strategie

Het wordt aanbevolen om een gelaagde fallback te implementeren: probeer eerst media te downloaden, bij succes — roep contentHandler aan met volledige inhoud; bij mislukking — roep contentHandler aan met tekst maar zonder media; bij kritieke fout — geef de originele inhoud door. Deze aanpak garandeert dat de gebruiker altijd een melding ziet, geen leeg scherm.

Volgens Apple is de meest voorkomende oorzaak van time-outs het downloaden van grote mediabestanden bij een trage verbinding. Om het risico te verminderen, wordt aanbevolen de afbeeldingsgrootte op de server te optimaliseren — stuur voorvertoningen tot 300 KB in plaats van volledige resolutie. Afbeeldingen met volledige resolutie kunnen beter worden gedownload bij het openen van de app.

Prestatiebewaking

Voor het volgen van time-outs en fouten van de extensie kan os_log worden gebruikt om diagnostische berichten naar het Unified Logging System te schrijven. Hoewel direct loggen naar een bestand in de extensie moeilijk is, maakt os_log prestatieanalyse mogelijk via Console.app op het ontwikkelaarsapparaat. Apple raadt aan om bij elke didReceive-aanroep metrieken toe te voegen — downloadtijd, bestandsgrootte, bewerkingsresultaat.

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