プッシュ通知 JSON ペイロードビルダー｜FCM と APNs の両形式を 1 画面で同時生成

モバイル開発で必要なプッシュ通知のテスト用 payload を、Firebase Cloud Messaging（FCM HTTP v1）と Apple Push Notification service（APNs）の両仕様で同時に組み立てます。タイトル・本文・バッジ数・サウンド・カスタムデータを 1 つのフォームに入力すると、左に FCM 形式、右に APNs 形式の JSON が生成され、コピーボタンで Postman や curl にそのまま貼り付けられます。

💡 このツールについて

iOS と Android の両プラットフォームに通知を実装するとき、FCM と APNs では JSON の階層が異なります。FCM HTTP v1 では message.notification.title/body の下にカスタムデータが message.data として並び、Android 固有設定は message.android.notification、APNs 経由送信用 override は message.apns.payload.aps に入ります。一方 APNs 単体形式では aps.alert.title/body の下に aps.badge aps.sound が並び、カスタムデータは aps の外側（root level）に置く必要があります。両者を行き来していると配置場所を間違えやすいため、同じ入力から両形式を並べて生成できると安全です。

🧐 よくある質問

Q: FCM legacy API (/fcm/send) との互換性はありますか? A: ありません。本ツールは 2024 年以降の正式仕様である HTTP v1 API（https://fcm.googleapis.com/v1/projects/{project}/messages:send）の payload 構造を生成します。legacy API は 2024 年 6 月で廃止されました。

Q: カスタムデータに数値や JSON object を入れられますか? A: 本ツールではすべて文字列として扱います。FCM HTTP v1 仕様で data 配下の value は string のみ許容されており、ネストした object は仕様違反になるためです。APNs の root level も同様に文字列推奨です。

Q: APNs の aps.sound に "default" 以外のファイル名は指定できますか? A: 本ツールは sound 切替が ON のとき "default" 固定で出力します。カスタムサウンドファイル名はコピー後に手動で書き換えてください。アプリ bundle に同梱した .caf ファイル名を指定する形式です。

Q: badge を 0 にしたい場合はどうなりますか? A: badge 欄を空のままにすると JSON から badge フィールド自体が省略されます。明示的に 0 を入れたい場合（アプリのバッジを消す用途）はコピー後に "badge": 0 を手で追加してください。

Q: 生成された JSON はそのまま送信できますか? A: payload 構造は仕様準拠ですが、実送信には FCM の OAuth 2.0 アクセストークンや APNs の JWT 認証ヘッダ・device token が別途必要です。本ツールは payload 部分のテンプレート生成専用です。

📚 FCM HTTP v1 と APNs の構造的な違い

FCM HTTP v1 と APNs の最大の違いは「カスタムデータの置き場所」と「プラットフォーム固有設定の階層」です。FCM は単一エンドポイントで Android / iOS / Web Push に配信するため、共通フィールド（notification.title/body）、プラットフォーム別 override（android.notification / apns.payload.aps / webpush.notification）、すべての受信側に渡すデータ（data）の 3 層構造を取ります。これにより同一ペイロードで Android では Big Text スタイル、iOS では alert 表示、Web では Service Worker 通知、と挙動を切り替えられます。

APNs は Apple 内製プロトコルなので、aps 辞書配下に Apple 仕様の予約フィールド（alert / badge / sound / category / thread-id / mutable-content 等）を置き、それ以外のキー（root level）はアプリ側で自由に解釈できる data として扱います。FCM 経由で APNs に送る場合は message.apns.payload の中に APNs 形式のオブジェクトをそのまま入れ子にする形になります。

実運用では Firebase Admin SDK（Node.js / Python / Java 等）を使うと共通フィールドを書くだけで両プラットフォームに自動分配されますが、デバッグや細かい挙動制御（バッジ動作・サウンド指定・mutable-content 等）では生 JSON で送信した方が確実なケースもあります。本ツールはそのような raw JSON 生成のためのテンプレート出力に最適です。