Web Push の通知描画は、W3C / WHATWG の標準仕様だけでなく、実行する OS（Windows / macOS / Android / iOS）、ブラウザ、およびユーザーの通知設定に強く依存します。
本稿では、Web Push 実装においてフロントエンド・PWA 開発者が押さえるべき 「showNotification 表示オプションのリファレンス」、「画像・ボタンの推奨仕様」、および 「OS×ブラウザ別の挙動差分」 を整理して解説します。
TL;DR（この記事の要点）
-
表示オプションは Progressive Enhancement：
imageやactions、iconはブラウザや OS の実装、ユーザー設定によって容易に無視・拡大縮小・切除される。titleとbodyだけで100%意味が通る設計が必須。 -
ピクセル値や容量は「Web標準の規定」ではなく「制作上の目安」：
-
icon: 1:1（256×256px程度が安全な目安）。192×192px未満は解像度不足の懸念あり。 -
image: 2:1（1024×512px等）や 16:9（1280×720px等）が基準として使われるが、OS/ブラウザでの切り抜き領域は保証されない。 -
badge: Android等のステータスバー表示向け。透明背景の単色シルエット推奨（システムがアルファ領域を抽出し着色するため）。
-
- iOS は PWA（ホーム画面追加アプリ）が必須：iOS / iPadOS ではブラウザの通常タブではなく、「ホーム画面に追加された PWA」から直接のユーザー操作で許可を取った場合のみ動作する。
1. showNotification(title, options) オプション完全リファレンス
title は NotificationOptions のプロパティではなく、showNotification(title, options) の必須第 1 引数です。各オプションの型、既定値、仕様上の意味は WHATWG Notifications API Living Standard に基づきます。
| 引数 / オプション | 型 | 既定値 | 仕様上の意味と実装時の注意点 |
|---|---|---|---|
title |
DOMString |
必須 | 第1引数。通知タイトル。OSによって文字数制限で折り返されるため先頭数文字に重要情報を置く |
body |
DOMString |
"" |
通知本文。表示行数はOSの通知表示形式（バナー/通知センター）や展開状態によって変化する |
dir |
"auto" | "ltr" | "rtl" |
"auto" |
テキストの読み方向。API自体は対応していてもOSの通知UIが無視する場合がある |
lang |
DOMString |
"" |
通知テキストの主要言語を示すBCP 47言語タグ。翻訳を行う機能ではなく、読み上げや文字処理などのヒントとして使用される |
tag |
DOMString |
"" |
同一 origin 内で通知を識別・更新（置換）するID。連投時に前回の通知を上書きできる |
image |
USVString |
未指定 | 通知内に大きく表示するコンテンツ画像URL。Android ChromeやWindows等でのみ対応（OS設定で非表示あり） |
icon |
USVString |
未指定 | 通知を補強する画像URL。Safari/iOSでは無視される。OSや通知種別によって切り抜きが異なる |
badge |
USVString |
未指定 | モバイル等の省スペース時に表示する画像URL。Android Chrome等でステータスバー用の小アイコンとして利用 |
vibrate |
VibratePattern |
未指定 | 振動パターン（配列）。対応ハードウェア（主にAndroid等）でのみ有効。silent: trueとの同時指定はTypeErrorになる |
timestamp |
EpochTimeStamp |
未指定 | 通知に関連する時刻（Unixミリ秒）。受信時刻ではなくイベント発生時刻を示したい場合に使用 |
renotify |
boolean |
false |
同じ tag の通知を置換した際に再音・再振動させるか。true にする場合は空でない tag が必須 |
silent |
boolean? |
null |
trueで音・振動を抑止。nullはプラットフォームの既定動作に従う。trueの場合はvibrateを指定できない |
requireInteraction |
boolean |
false |
ユーザーが操作するまで通知を表示し続ける選好。常駐を完全に保証するものではない |
data |
any |
null |
通知クリックイベント等で参照する構造化複製可能なデータ。シリアライズできない値はDataCloneErrorになり、UIには表示されない |
actions |
sequence<NotificationAction> |
[] |
アクションボタンの配列。表示上限数は Notification.maxActions や OS 描画限界に依存 |
navigate |
USVString |
未指定 | Living Standardで定義された遷移URL。指定時はnotificationclickを経由せず直接遷移する。実装状況を確認し、外部入力はsame-originまたは明示的なallowlistで検証する |
2. 画像・ボタンの設計ガイドライン（推奨仕様とOS×ブラウザ別詳細挙動）
WHATWG Notifications API 標準 には、画像の解像度・アスペクト比・容量上限に関する厳密な規定はありません。以下に示すピクセル値や容量は、Web標準の必須条件ではなく、各プラットフォームの実装を踏まえた「制作上の初期値・目安」 です。
🖼️ 2.1 アイコン (icon)
-
実務上の推奨解像度:
256 × 256 px程度（高DPI表示での視認性を考慮。192×192px 未満は解像度不足の懸念あり） -
アスペクト比:
1:1（正方形） - 容量・ファイル形式: Web標準による共通上限はなく、ブラウザやOSの実装に依存します。取得失敗や表示遅延を避けるため、可能な限り圧縮・軽量化します。
-
OS × ブラウザごとの表示・挙動:
- Android (Chrome / Firefox): Android 通知デザインガイド に従い、通知の種別（人物関連か一般通知か等）や端末・OSのテンプレートによって、円形マスクまたは正方形・角丸で表示されます。
- Windows / macOS (Chrome / Edge / Firefox): 正方形または角丸正方形で通知カード内等に配置されます。
-
macOS / iOS (Safari):
NotificationOptions.iconで指定した URL は無視されます。通常Webサイトからの通知ではSafariアイコン、インストール済み PWA からの通知では PWA のアイコンなど、起動起点や動作モードに応じたシステムアイコンが表示されます。
🖼️ 2.2 大画像バナー (image)
-
制作上の参考比率:
2:1（1024×512px等）や16:9（1280×720px等）が基準として使われることが多い -
表示条件と注意点:
- Android (Chrome) / Windows (Chrome / Edge 等): 通知のスタイルや展開状態（Androidのスワイプ展開やWindows ToastのHero Image表示等）に応じて大画像が表示されます。
-
macOS (Chrome / Edge / Safari / Firefox): macOS のネイティブ通知センター（UNUserNotificationCenter）構造には Chromium の
image画像を描画する領域がないため、**macOS 上の Chrome や Edge でもimageは描画されず無視（実質未対応）**となります。 -
Firefox / Safari (全プラットフォーム):
imageプロパティは未対応（無視）のため表示されません（MDN Browser Compatibility Dataに準拠）。 - 画面切り抜きへの考慮: 表示領域やアスペクト比はOS・端末・画面向きによって切り詰められる可能性があるため、重要な被写体やテキスト画像は中央に寄せて配置します。
🖼️ 2.3 バッジ (badge)
-
実務上の推奨解像度:
72 × 72 pxや96 × 96 px程度（1:1 正方形） - デザイン推奨: 透明背景の単色（モノクロ）シルエット画像
-
OS × ブラウザごとの表示・挙動:
- Android (Chrome): 画面最上部のステータスバー（通知エリア）等に表示されます。アルファチャンネル（透明度領域）をもとにシステムが着色・シルエット化して描画します。
-
デスクトップOS / iOS / Firefox 等: デスクトップOSやiOS等の通知バナー/通知センターの描画構造には
badge画像の表示領域が存在しないため**実質非表示（無視）**となります（MDN Browser Compatibility Dataに準拠）。 -
※補足: iOS のホーム画面アイコン右上に表示される「赤丸の数値バッジ」は、この
badgeオプションではなくnavigator.setAppBadge()や Declarative Web Push のapp_badgeで制御します。
🔘 2.4 アクションボタン (actions)
-
最大表示可能数:
Notification.maxActions（動的プロパティ）を必ず参照して判定- Androidネイティブ通知自体は最大3アクションに対応していますが、Web Pushでは
Notification.maxActionsの値を判定して動的にボタン数を設定します。 -
Safari (macOS / iOS):
actions未対応（maxActionsは 0）。
- Androidネイティブ通知自体は最大3アクションに対応していますが、Web Pushでは
-
NotificationActionのパラメータ構成:-
action: アクション識別ID（例:"open","dismiss"）。 -
title: ボタンの表示テキスト（画面幅により省略されるため簡潔な表記を推奨）。 -
icon: ボタン横の小アイコンURL。ただしAndroid 7以降をはじめ多くの環境でアクションアイコンは描画されないため、アイコンに意味を依存させない設計にします。 -
navigate: Living Standard で定義された遷移先URL。実装ブラウザは限定的です。指定時はnotificationclickを経由せず直接遷移するため、外部入力はsame-originまたは明示的なallowlistで検証します。
-
-
ボタン非表示環境への配慮:
- モバイルでの折りたたみ時や Safari / iOS のようにアクションボタン非対応の環境では、ユーザーは通知本体をクリックします。ボタンが表示されない環境でも「通知カード全体のクリック」で主要動線へ進めるよう実装してください。
3. OS × ブラウザ別 挙動差分マトリクス（2026年最新）
2026年7月23日時点の主要環境におけるサポート状況です。WHATWG Notifications API、MDN Browser Compatibility Data 8.0.7、および各OSの通知UI仕様を照合しています。
- ✅: ブラウザが対応し、通常は指定した効果がOSにも反映される
- ⚠️: APIは受け付けるが、OSの通知UI・端末・ユーザー設定によって表示や効果が制限または無視される
- ❌: ブラウザ未対応、または指定しても効果がない
- ➖: 対応しているが、通知UIには表示されない内部データ
3.1 デスクトップ環境の差分
| オプション | Windows (Chrome / Edge) | Windows (Firefox) | macOS (Safari) | macOS (Chrome / Edge) | macOS (Firefox) |
|---|---|---|---|---|---|
title（第1引数） |
✅ 表示 | ✅ 表示 | ✅ 表示 | ✅ 表示 | ✅ 表示 |
body |
✅ 表示 | ✅ 表示 | ✅ 表示 | ✅ 表示 | ✅ 表示 |
dir |
⚠️ 指定値を保持するがUIで無視される場合あり | ⚠️ 同左 | ⚠️ 同左 | ⚠️ 同左 | ⚠️ 同左 |
lang |
⚠️ 対応（見た目への反映は限定的） | ⚠️ 同左 | ⚠️ 同左 | ⚠️ 同左 | ⚠️ 同左 |
tag |
✅ 置換対応 | ✅ 置換対応 | ❌ 設定可能だが効果なし | ✅ 置換対応 | ✅ 置換対応 |
image |
⚠️ 対応（表示形式・設定依存） | ❌ 未対応 | ❌ 未対応 | ⚠️ API対応、macOS通知UIでは画像非表示 | ❌ 未対応 |
icon |
✅ 対応 | ✅ 対応 | ❌ 指定URLは無視（Safari/PWAアイコン） | ⚠️ 対応（OSの配置・切り抜き依存） | ⚠️ 対応（OSの配置・切り抜き依存） |
badge |
⚠️ API対応、専用の描画領域なし | ❌ 未対応 | ❌ 未対応 | ⚠️ API対応、専用の描画領域なし | ❌ 未対応 |
vibrate |
⚠️ API対応、対応ハードウェア・OS設定依存 | ❌ 未対応 | ❌ 未対応 | ⚠️ API対応、通常は効果なし | ❌ 未対応 |
timestamp |
⚠️ API対応、時刻表示はOS依存 | ❌ 未対応 | ❌ 未対応 | ⚠️ API対応、時刻表示はOS依存 | ❌ 未対応 |
renotify |
⚠️ 対応（空でないtagが必須、音設定依存） |
❌ 未対応 | ❌ 未対応 | ⚠️ 対応（空でないtagが必須、音設定依存） |
❌ 未対応 |
silent |
✅ 対応 | ✅ Firefox 132+ | ✅ Safari 16.6+ | ✅ 対応 | ✅ Firefox 132+ |
requireInteraction |
⚠️ 対応（常駐保証なし） | ⚠️ Windowsのみ既定で対応 | ❌ 未対応 | ⚠️ 対応するがmacOSの通知設定優先 | ⚠️ 既定無効（設定フラグで有効化可能） |
data |
➖ 対応（UI非表示） | ➖ 対応（UI非表示） | ➖ Safari 16+（UI非表示） | ➖ 対応（UI非表示） | ➖ 対応（UI非表示） |
actions |
✅ 対応（maxActions順守） |
✅ Firefox 152+ | ❌ 未対応 | ⚠️ 対応（「その他」メニュー等に格納される場合あり） | ⚠️ Firefox 152+（メニュー格納の場合あり） |
navigate |
❌ 未対応 | ❌ 未対応 | ✅ Safari 18.4+ | ❌ 未対応 | ❌ 未対応 |
3.2 モバイル環境の差分
| オプション | Android (Chrome / Chromium) | Android (Firefox) | iOS / iPadOS (PWA: ホーム画面追加) |
|---|---|---|---|
title（第1引数） |
✅ 表示 | ✅ 表示 | ✅ 表示 |
body |
✅ 表示 | ✅ 表示 | ✅ 表示 |
dir |
⚠️ 指定値を保持するがUIで無視される場合あり | ⚠️ 同左 | ⚠️ 同左 |
lang |
⚠️ 対応（見た目への反映は限定的） | ⚠️ 同左 | ❌ 未対応 |
tag |
✅ 置換対応 | ✅ 置換対応 | ❌ 未対応 |
image |
✅ 対応（スワイプ展開等） | ❌ 未対応 | ❌ 未対応 |
icon |
⚠️ 対応（描画はOS・通知種別依存） | ⚠️ 対応（描画はOS依存） | ❌ 指定URLは無視（PWAアイコン表示） |
badge |
✅ ステータスバー用小アイコン | ❌ 未対応 | ❌ 未対応（数値バッジはsetAppBadge()） |
vibrate |
⚠️ 対応（端末・通知チャネル・ユーザー設定優先） | ❌ 未対応 | ❌ 未対応 |
timestamp |
⚠️ API対応、時刻表示はOS依存 | ❌ 未対応 | ❌ 未対応 |
renotify |
⚠️ 対応（空でないtagが必須、通知チャネル依存） |
❌ 未対応 | ❌ 未対応 |
silent |
✅ 対応 | ✅ Firefox 132+ | ✅ 対応（通知音のユーザー設定優先） |
requireInteraction |
⚠️ API対応、Androidでは効果なし | ⚠️ 既定無効（設定フラグで有効化可能） | ❌ 未対応 |
data |
➖ 対応（UI非表示） | ➖ 対応（UI非表示） | ➖ 対応（UI非表示） |
actions |
✅ 対応（maxActions順守） |
✅ Firefox 152+ | ❌ 未対応 |
navigate |
❌ 未対応 | ❌ 未対応 | ✅ Safari 18.4+ |
title は options の一部ではなく必須の第1引数ですが、完全性のため表に含めています。data はOSの通知UIへ表示する項目ではなく、notificationclick などで利用する内部データです。iOS / iPadOS PWA の silent は、AppleがWeb Appの通知音制御として案内している挙動に基づきます。
また、上表の navigate はトップレベルの NotificationOptions.navigate を指します。navigate は実験的機能で対応ブラウザが限られるため、クロスブラウザ実装では引き続き notificationclick と clients.openWindow() を基本にしてください。
なお、macOSでは通知を「一時的」または「持続的」にする設定をユーザーが管理します。現行Chromeでは requireInteraction を指定できますが、Chrome 152以降のインストール済みPWAに適用されるネイティブ通知帰属では同オプションが無視されるため、常駐を前提に設計しないでください。
4. 用語集
| 用語 | 意味 |
|---|---|
| Web Push | Webアプリへサーバーからメッセージを届ける仕組みの総称。Push API、Service Worker、Notifications APIなどを組み合わせて実現する |
| Push API | Pushサービスの購読（PushSubscription）と、Service Workerでのpushイベント受信を扱うAPI。通知UIの表示自体は担当しない |
| Notifications API | OSの通知UIへ通知を表示・管理するAPI。Service Workerではregistration.showNotification()を使用する |
| Service Worker | Webページとは別にバックグラウンドで実行されるイベント駆動型スクリプト。Web Pushではpushやnotificationclickイベントを処理する |
| PWA（Progressive Web App） | Web技術で構築しながら、インストールやオフライン動作などアプリに近い体験を提供するWebアプリ。iOS / iPadOSのWeb Pushではホーム画面へ追加されたPWAが必要 |
NotificationOptions |
showNotification(title, options)の第2引数として渡す辞書型。body、icon、actionsなど通知の内容や挙動を指定する |
NotificationAction |
actions配列の各要素を表す辞書型。アクション識別子、表示テキスト、アイコン、遷移先などを指定する |
| Persistent Notification | Service WorkerのshowNotification()で作成する永続通知。Webページのライフサイクルから独立して通知センターに保持できるという仕様上の分類であり、画面上への常駐を要求するrequireInteractionとは意味が異なる |
| Progressive Enhancement | 最低限の情報や機能を全環境へ提供し、対応環境でのみ画像やアクションなどを追加する設計方針。本稿ではtitleとbodyだけでも意味が通る設計を指す |
| Origin（オリジン） | URLのスキーム、ホスト、ポートの組み合わせ。通知のtagによる置換や権限、Service Workerの制御範囲を分けるセキュリティ境界 |
| BCP 47 |
ja、en-USなど、言語を識別するタグの形式を定めた仕様。langオプションで使用する |
| MDN Browser Compatibility Data（BCD） | Web APIやCSSなどのブラウザ対応状況を機械可読な形式で管理するMDNの互換性データ。本稿のブラウザ対応判定に使用している |
| 通知チャネル（Notification Channel） | Android 8.0以降で通知の重要度、音、振動などを分類・制御するOS側の仕組み。Web側の指定よりユーザーが選んだチャネル設定が優先される場合がある |
badgeオプション |
通知UIの省スペース表示に使う小画像。主にAndroidのステータスバー用で、アプリアイコン上の未読件数バッジとは別物 |
| App Badging API |
navigator.setAppBadge()などでアプリアイコンに件数や状態を表示するAPI。NotificationOptions.badgeとは用途もAPIも異なる |
| ネイティブ通知帰属 | 通知をブラウザではなくインストール済みPWA自身からの通知としてOSへ関連付ける仕組み。アプリ名・アイコン・通知設定の単位に影響する |
5. 参照仕様・公式ドキュメント一覧
本稿の各数値および仕様差分は、以下の公式標準仕様およびベンダー公式リファレンスに基づいています。
- 標準仕様・ブラウザ標準
- Google / Android
- Apple WebKit
- Microsoft Windows / Edge
まとめ
Web Push はブラウザや OS ごとに表示・挙動の差分が大きく存在します。
「ピクセル値やアスペクト比はWeb標準の規定ではなく制作上の目安である」こと、「どの環境でも共通して信頼できるのは title と body である」という原則を押さえ、表示オプションは Progressive Enhancement として設計することが、安定した Web Push 実装の鍵となります。