Notification Service Extension — bagaimana pemrosesan notifikasi bekerja

Apa itu Notification Service Extension

Notification Service Extension adalah ekstensi aplikasi di iOS yang mencegat notifikasi push yang masuk di sisi perangkat dan memungkinkan perubahan kontennya sebelum pengguna melihatnya. Ini adalah satu-satunya jenis ekstensi notifikasi yang bekerja dengan konten, bukan dengan tampilan.

Perbedaan utama dengan Notification Content Extension: Service Extension bekerja sebelum notifikasi ditampilkan dan dapat mengubah judul, tubuh, file suara, dan lampiran. Content Extension bekerja setelah ditampilkan dan hanya mengelola presentasi visual dari notifikasi yang sudah jadi. Kedua ekstensi ini dapat bekerja bersama: Service Extension mengunduh gambar, dan Content Extension menampilkannya di antarmuka khusus.

Ekstensi diaktifkan secara otomatis saat menerima notifikasi push dengan atribut mutable-content:1 di kamus aps. iOS menjalankan ekstensi di latar belakang, mengirimkan UNNotificationRequest asli, dan menunggu versi yang dimodifikasi untuk ditampilkan.

Memproses notifikasi push dengan cepat

UNNotificationServiceExtension menerima UNNotificationRequest lengkap dengan konten asli. Ekstensi dapat memodifikasi bidang UNNotificationContent apa pun: title, subtitle, body, userInfo, attachments, dan sound. Perubahan diterapkan sebelum notifikasi ditampilkan.

Skenario penggunaan umum

Dekripsi konten — jika notifikasi push berisi payload terenkripsi, ekstensi mendekripsinya sebelum ditampilkan. Unduh media — melampirkan gambar atau video ke notifikasi. Lokalisasi — menyesuaikan teks notifikasi dengan pengaturan regional perangkat. Pengayaan data — menambahkan informasi tambahan dari penyimpanan lokal atau cache.

Menurut Apple, skenario paling umum di antara aplikasi adalah mengunduh gambar untuk notifikasi media yang kaya. Server mengirim URL gambar dalam payload, ekstensi mengunduhnya ke direktori sementara dan membuat UNNotificationAttachment yang ditampilkan sistem di antarmuka standar atau khusus.

Memodifikasi teks dan judul

Ekstensi dapat menulis ulang teks notifikasi sepenuhnya, mengganti judul, atau menambahkan subtitle. Misalnya, aplikasi perpesanan dapat menerima notifikasi terenkripsi, mendekripsinya di ekstensi, dan menampilkan teks yang dapat dibaca. Atau aplikasi berita dapat menambahkan kategori berita ke subjudul sebelum ditampilkan.

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

Protokol UNNotificationServiceExtension

UNNotificationServiceExtension — kelas dasar yang diwarisi oleh Service Extension. Kelas ini mendefinisikan dua metode siklus hidup: didReceive(_:withContentHandler:) — metode pemrosesan utama, dan serviceExtensionTimeWillExpire() — penangan kedaluwarsa waktu.

Metode didReceive:withContentHandler:

didReceive(_:withContentHandler:) dipanggil saat menerima notifikasi. Ekstensi menerima UNNotificationRequest dan closure contentHandler yang harus dipanggil dengan UNMutableNotificationContent yang dimodifikasi. Ekstensi wajib memanggil contentHandler — jika tidak, iOS akan menampilkan notifikasi asli setelah waktu habis.

Penting: ekstensi hanya dapat memproses satu notifikasi dalam satu waktu. Jika beberapa notifikasi tiba secara bersamaan, iOS membuat instance ekstensi terpisah untuk masing-masing. Status global tidak dapat digunakan untuk pemrosesan berurutan.

Metode serviceExtensionTimeWillExpire:

serviceExtensionTimeWillExpire() dipanggil oleh sistem ketika sisa waktu eksekusi hampir habis. Dalam metode ini, segera panggil contentHandler dengan konten yang sudah siap saat itu — bahkan jika file media belum diunduh. Jika contentHandler tidak dipanggil dalam metode ini, iOS akan menampilkan notifikasi asli.

Disarankan untuk menyimpan konten minimum yang dapat diterima dalam metode ini — misalnya, notifikasi dengan teks dan judul, tetapi tanpa gambar yang unduhannya belum selesai tepat waktu.

Enkripsi dan lampiran media

UNNotificationAttachment — objek yang dibuat oleh ekstensi untuk melampirkan file media ke notifikasi. Ekstensi mengunduh file dari jaringan, menyimpannya di direktori sementara, dan membuat UNNotificationAttachment dengan menentukan jenis konten.

Membuat lampiran dari file yang diunduh

UNNotificationAttachment dibuat menggunakan inisialisasi init(identifier:url:options:). URL harus menunjuk ke file lokal di direktori sementara yang dapat diakses oleh ekstensi. Setelah dibuat, lampiran ditambahkan ke array attachments dari UNMutableNotificationContent.

Apple merekomendasikan penggunaan URLSession dengan konfigurasi latar belakang untuk mengunduh — saat menggunakan URLSession standar, pengunduhan memblokir thread dan menghabiskan waktu dari batas 30 detik. URLSession latar belakang melanjutkan pengunduhan bahkan setelah ekstensi berakhir, dan hasilnya dapat digunakan pada saat startup berikutnya.

Mendekripsi payload terenkripsi

Jika server mengirim notifikasi terenkripsi, ekstensi harus mendekripsi payload sebelum memanggil contentHandler. Dekripsi biasanya melibatkan permintaan kunci dari Keychain atau App Group, dekripsi melalui CommonCrypto, dan penggantian body atau userInfo notifikasi. Jika terjadi kesalahan dekripsi, contentHandler harus dipanggil dengan konten asli — sehingga pengguna setidaknya melihat bahwa notifikasi telah tiba, meskipun tidak terbaca.

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-out dan mekanisme fallback

Notification Service Extension bekerja dalam batas waktu yang ketat. iOS mengalokasikan waktu eksekusi tetap — sekitar 30 detik sejak aktivasi. Jika ekstensi tidak memanggil contentHandler dalam waktu ini, sistem secara paksa menghentikan proses dan menampilkan notifikasi asli tanpa perubahan.

Strategi graceful degradation

Disarankan untuk menerapkan fallback bertingkat: pertama coba unduh media, jika berhasil — panggil contentHandler dengan konten lengkap; jika gagal — panggil contentHandler dengan teks tetapi tanpa media; jika terjadi kesalahan kritis — teruskan konten asli. Pendekatan ini menjamin bahwa pengguna selalu melihat notifikasi, bukan layar kosong.

Menurut Apple, penyebab paling umum dari time-out adalah pengunduhan file media besar pada koneksi lambat. Untuk mengurangi risiko, disarankan untuk mengoptimalkan ukuran gambar di server — kirim pratinjau hingga 300 KB, bukan resolusi penuh. Gambar resolusi penuh sebaiknya diunduh saat membuka aplikasi.

Pemantauan kinerja

Untuk melacak time-out dan kesalahan ekstensi, dapat digunakan os_log untuk menulis pesan diagnostik ke Unified Logging System. Meskipun pencatatan langsung ke file di ekstensi sulit dilakukan, os_log memungkinkan analisis kinerja melalui Console.app di perangkat pengembang. Apple merekomendasikan menambahkan metrik pada setiap panggilan didReceive — waktu unduh, ukuran file, hasil operasi.

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