Notification Service Extensionでリッチ通知を実装してつまずいた話

PencilKitで手書き入力機能を実装した後、以前プッシュ通知（リモート通知）を実装した経験を踏まえ、画像付きのリッチ通知に挑戦しました。

1. 既存のプッシュ通知処理をそのまま拡張すればよいと思っていた

最初、以前実装したアプリ本体のプッシュ通知処理に手を加えれば画像が表示できるようになると思い込んでいました。

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any]) {
    // 通知受信処理
}

しかし、この処理をいくら修正しても通知に画像は表示されませんでした。調べてみると、リッチ通知の実現にはアプリ本体とは別の「Notification Service Extension」という独立したターゲットを新規に追加する必要があると分かりました。

Xcodeで新規ターゲットとしてNotification Service Extensionを追加したものの、それだけでは画像が表示されませんでした。

不足していた設定:
プッシュ通知ペイロードへのmutable-contentキーの追加

サーバー側から送るプッシュ通知のペイロードにmutable-contentキーを含めていないと、OSがExtensionを呼び出さない仕組みになっていることが分かりました。テスト用のペイロードにこのキーを追加し、Extension側の処理が呼ばれるようになりました。

Extensionが呼ばれるようになった後、通知ペイロードに画像のURLを含めるだけで自動的に表示されると思っていました。

let attachment = try? UNNotificationAttachment(identifier: "image", url: imageURL, options: nil)

実際には、リモートURLをそのままUNNotificationAttachmentに渡してもエラーになりました。画像を一度ローカルにダウンロードしてファイルとして保存し、そのローカルファイルのURLを使って添付ファイルを生成する必要があると分かり、ダウンロード処理を挟む実装に変更しました。

Extensionの実装が完成したと思い、シミュレータでリモート通知をテストしていましたが、画像がまったく表示されず原因が分からず悩みました。

検証方法:
実機にAPNsで実際のプッシュ通知を送信して確認

調べてみると、リモートプッシュ通知（APNs経由）を使った動作確認はシミュレータでは制約が多く、Notification Service Extensionを含む挙動は実機での確認が確実だと分かりました。実機に切り替えてテスト送信したところ、期待通り画像付きの通知が表示されました。

以前実装したプッシュ通知の知識だけでは足りない部分が多く、Extensionという仕組みとペイロード設計の両方を理解する必要がある実装でした。

本記事は生成AI（Claude）を活用して執筆・編集しています。内容は実体験に基づき、執筆者本人が確認・監修しています。