Webプッシュ通知が届かない？5分で解決するトラブルシューティングガイド

通知が届かない。開発コンソールは沈黙している。多くの場合、これはコードのバグではなく、権限設定の連鎖がどこかで切断された状態に過ぎない。Webプッシュのアーキテクチャを考慮すると、障害発生ポイントは大きく3つのレイヤーに収束する。ブラウザのUI設定、OSレベルの通知許可、そしてエンドポイントとVAPID鍵の整合性。これらを順に剥がしていくだけで、大半のケースは短時間で解決する。

結論から言う。テスト環境で動作する通知が本番で止まるなら、ネットワーク経路かプロキシのフィルタリングを疑え。ローカルでも動かないなら、Service Workerの登録スコープとパーミッションダイアログの表示順序を見直す作業を実施する。

ステップ1：ブラウザとOSの権限階層を解体する

通知の配信が阻まれる原因の多くは、開発者ツールの「Application」タブを参照すれば判明する。ここで PushManager.subscribe() の実行結果が null を返す場合、ブラウザのサイト設定が「ブロック」に倒れている。あるいはOS側、特にmacOSやWindows 11のシステム設定で、ブラウザ自体の通知権限が無効化されているケースが散見される。単に設定を切り替えるのではなく、OSの通知センターとブラウザのプロファイル設定を並べて照合する作業を進める。権限が競合している場合、ブラウザは沈黙したままリクエストを破棄する挙動を示す。

ステップ2：オンラインテストツールを用いたエンドポイント検証

Service Workerが push イベントを発火させているか確認するには、実際のペイロードを投げる必要がある。curlコマンドやオンラインのプッシュテストツールを活用し、subscription.endpoint および subscription.keys.auth、subscription.keys.p256dh を直接指定してリクエストを送出する処理を行う。ここで 201 Created が返るなら、サーバーサイドの配信ロジックは正常に動作している。問題の切り分けはこれで完了する。返ってくるステータスが 400 Bad Request や 404 Not Found に変化する場合、エンドポイントの期限切れかVAPID鍵の不一致を疑う。クライアント側で PushSubscription オブジェクトの再生成処理を実行させる設定を組み込む。

ステップ3：プッシュ受信テストの実施とイベントリスナーの追跡

通知が飛ぶのに画面に現れない。この現象は、Service Workerの notificationclick や push イベントハンドラが正しくアタッチされていない、あるいはバックグラウンドでエラーを握り潰している場合に発生する。navigator.serviceWorker.controller の存在有無を確認を進める。コンソールに Uncaught (in promise) が出力されているなら、非同期処理の完了前にスレッドが終了している。イベントハンドラ内で event.waitUntil() を用いてPromiseチェーンを明示的に待機させる設定を行う。この制御を見落とすだけで、ブラウザは通知を破棄する挙動を示す。

ステップ4：OS/ブラウザ更新後の互換性崩れへの対応

ChromeやFirefoxのメジャーアップデート後、突然通知が止まる現象は決して珍しくない。主な背景要因として、ブラウザエンジンのセキュリティポリシー変更や、VAPIDライブラリの内部実装変更が挙げられる。service-worker.js のキャッシュバージョンを強制的に更新し、クライアント側のキャッシュ破棄処理を実施する。同時に、旧バージョンのブラウザ向けに subscriptionchange イベントを監視する処理を設けておく。通知権限の付与状態が default にリセットされる仕様変更には、ユーザー体験を損なわない範囲で再同意フローをトリガーする準備を進める。

ステップ5：本番環境での安定性検証と品質劣化の切り分け

デモやオンライン授業の直前に動作を確認したい場合、負荷テストツールで並列配信を行い、レイテンシと到達率を計測する作業を進める。FCMやAutopushのバックエンドに依存している場合、トークンの有効期限が切れるタイミングでのリフレッシュ処理がボトルネックになることが多い。サーバーログで gcm/endpoint や autopush/endpoint へのリトライ回数を追跡する。到達率が低下している場合、ユーザーのデータセーバー設定やモバイルネットワークのAPN制限が影響を及ぼしている可能性がある。これらを除外するには、Wi-Fi環境とモバイル回線での挙動を比較検証する手順を実施する。

結局のところ、Webプッシュ通知は魔法ではなく、HTTPとService Workerの規約で動いている。権限階層の把握、エンドポイントの正当性検証、イベント待機の厳格な制御。この3点を押さえれば、大半のトラブルは消える。テスト環境での再現性を高め、本番リリース前のチェックリストに組み込んでおく。そうすれば、緊急時のデモでも慌てずに対処を進められる。