capacitor-push-notifications

Capacitor Push Notifications

@capacitor-firebase/messaging プラグインを使って Firebase Cloud Messaging（FCM）経由のプッシュ通知を設定し、Capacitor アプリで使用します。

前提条件

1. Capacitor 6、7、または 8 のアプリ。
2. Node.js と npm がインストールされていること。
3. Firebase プロジェクト。必要に応じて Firebase コンソールで作成してください。
4. iOS の場合：有料の Apple Developer Program メンバーシップと、Xcode がインストールされていること。
5. Android の場合：Android Studio がインストールされていること。
6. @capacitor/push-notifications はインストールしないでください。@capacitor-firebase/messaging と競合します。

エージェントの動作

• 手順を一つずつ案内する。 プロセスを一度に一つずつユーザーに案内します。関係のない質問を複数同時に提示しないでください。
• 質問する前に自動検出する。 プロジェクトのプラットフォーム（android/、ios/）、ビルドツール、フレームワーク、package.json の依存関係を確認します。検出できない場合に限り、ユーザーに質問してください。
• 一度に一つの判断をする。 手順でユーザーの入力が必要な場合は、その質問だけをして回答を待ってから続行します。
• 選択肢を明確に提示する。 自由回答形式ではなく、具体的な選択肢（例：「トピックのサブスクリプションを設定しますか？（はい／いいえ）」）を提示します。

MCP サーバー

現在のドキュメントを提供するホスト型 MCP サーバーが 2 つあります。どちらも、このスキルに含まれるガイダンスより常に最新です。

• Capawesome MCP server — Capawesome プラグイン、Capawesome CLI、Capawesome Cloud を扱います。
• Capacitor MCP server（非公式）— Capacitor 自体を扱います。CLI、capacitor.config ファイル、ネイティブの Android および iOS プロジェクト、公式プラグイン API が対象です。

どちらも search_docs と get_doc_page を提供するため、いずれかを呼び出す前に、トピックに応じたサーバーを選んでください。

• MCP ツールが利用できる場合は、トピックを担当するサーバーで search_docs を呼び出し、一致するページを get_doc_page で読んでから、以下のガイダンスを適用してください。両者の内容が異なる場合は、ドキュメントに従ってください。
• MCP ツールが利用できない場合は、以下のコマンドでサーバーを追加できることを一度だけ伝えてから、このスキルを続けてください。利用できないことを理由に処理を止めないでください。

claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"
claude mcp add --transport http capacitor "https://capacitor-mcp.capawesome.io/mcp"

ドキュメントの利用にアカウントやトークンは必要ありません。Capawesome Cloud ツールを含む完全なセットアップについては、capawesome-mcp および capacitor-mcp スキルを参照してください。

手順

ステップ 1：プロジェクトを分析する

プロジェクトファイルを読み取り、以下を自動検出します。推測できる情報をユーザーに尋ねないでください。

1. プラットフォーム：存在するディレクトリ（android/、ios/）を確認します。これらが設定対象のプラットフォームです。
2. ビルドツール／フレームワーク：vite.config.ts、angular.json、webpack.config.js、next.config.js などを確認します。
3. Capacitor のバージョン：package.json から @capacitor/core のバージョンを読み取ります。
4. 競合するプラグイン：package.json に @capacitor/push-notifications があるか確認します。見つかった場合は、続行する前に削除する必要があることをユーザーに警告してください。

   npm uninstall @capacitor/push-notifications
   

ステップ 2：Firebase をセットアップする

Firebase がすでにプロジェクトで設定されているか確認します。

• Android：android/app/google-services.json が存在するか確認します。
• iOS：ios/App/App/GoogleService-Info.plist が存在するか確認します。

検出されたプラットフォームで Firebase が設定されていない場合は、references/firebase-setup.md を読み、不足している各プラットフォームの Firebase セットアップをユーザーに案内します。

ステップ 3：プラグインをインストールする

npm install @capacitor-firebase/messaging firebase
npx cap sync

ステップ 4：Android を設定する

android/ が存在しない場合はスキップします。

references/android-setup.md を読み、Android 固有の設定を適用します。

ステップ 5：iOS を設定する

ios/ が存在しない場合はスキップします。

references/ios-setup.md を読み、iOS 固有の設定を適用します。これには APNs キー／証明書のセットアップ、AppDelegate.swift の変更、ケイパビリティの有効化が含まれます。

ステップ 6：Web の設定（該当する場合）

プロジェクトが Web を対象としている場合（ビルドツールの設定またはユーザーへの確認によって判定）、

references/web-setup.md を読み、Web 固有の設定を適用します。

ステップ 7：Capacitor プラグインのオプションを設定する

iOS のフォアグラウンド通知の表示方法をカスタマイズするか、ユーザーに確認します。カスタマイズする場合は、capacitor.config.json または capacitor.config.ts を更新します。

{
  "plugins": {
    "FirebaseMessaging": {
      "presentationOptions": ["alert", "badge", "sound"]
    }
  }
}

使用可能なオプションは、badge、sound、alert、criticalAlert です。デフォルトは ["alert", "badge", "sound"] です。

ステップ 8：プッシュ通知のコードを追加する

references/implementation.md を読み、プッシュ通知のコードをプロジェクトに追加します。ユーザーのフレームワークに合わせて、インポートと構成を調整します。

実装には、以下が含まれます。

1. 権限のリクエスト
2. FCM トークンの取得
3. 通知の受信のリスニング
4. 通知のタップへの対応

ステップ 9：オプション機能を設定する

有効にするオプション機能をユーザーに確認します。

1. トピックのサブスクリプション — FCM トピックを登録／登録解除します（Android／iOS のみ）。
2. 通知チャンネル — カスタムの Android 通知チャンネルを作成します（Android SDK 26 以降のみ）。
3. トークン更新リスナー — FCM トークンの変更をリッスンします。

選択された機能ごとに、references/implementation.md を読み、該当するコードを適用します。

ステップ 10：同期してテストする

1. プロジェクトを同期します。

   npx cap sync
   

2. references/testing.md を読み、Firebase コンソールからテスト通知を送信する手順をユーザーに案内します。

エラー処理

• @capacitor/push-notifications との競合：@capacitor-firebase/messaging プラグインは @capacitor/push-notifications と共存できません。競合するプラグインをアンインストールします：npm uninstall @capacitor/push-notifications && npx cap sync。
• iOS：プッシュ通知を受信できない：APNs キー／証明書が Firebase コンソールにアップロードされていることを確認します。Push Notifications および Background Modes の機能が有効になっていることを確認します。AppDelegate.swift に必要なデリゲートメソッドが含まれていることを確認します。
• iOS：didRegisterForRemoteNotificationsWithDeviceToken が呼び出されない：Xcode の Signing & Capabilities で Push Notifications 機能が追加されていることを確認します。アプリのバンドル ID が Firebase および Apple Developer ポータルに登録されているものと一致することを確認します。
• Android：プッシュ通知を受信できない：google-services.json が android/app/google-services.json にあることを確認します。Google サービスの Gradle プラグインが適用されていることを確認します。
• Android：通知アイコンが白い四角になる：通知アイコンは、透明な背景に白いピクセルで作成する必要があります。色付きのアプリアイコンは白い四角として表示されます。専用のプッシュ通知アイコンを追加します。
• Web：getToken() が失敗する：VAPID キーが正しいことを確認します。firebase-messaging-sw.js がドメインのルートにあることを確認します。ブラウザーが Push API をサポートしていることを確認します。
• FCM トークンが null になる：getToken() の呼び出し前に requestPermissions() が呼び出され、granted が返されていることを確認します。iOS では、デバイスがシミュレーターではないことを確認します（シミュレーターではプッシュ通知を受信できません）。
• checkPermissions() が denied を返す：ユーザーが通知の権限を恒久的に拒否しています。デバイスの設定（設定 > アプリ > 通知）から再度有効にするよう案内します。
• Android 13 以降：権限の確認画面が表示されない：Android 13（API 33）以降では、requestPermissions() を明示的に呼び出す必要があります。それ以前の Android バージョンでは、通知の権限はデフォルトで許可されます。

関連スキル

• capacitor-app-development — Capacitor 開発全般のトピック、トラブルシューティング、ベストプラクティスについて説明します。
• capacitor-plugins — 他の Firebase プラグインを含む、Capacitor プラグインのインストールと設定全般について説明します。
• capawesome-mcp — MCP クライアントをホスト型 Capawesome MCP サーバーに接続し、常に最新のドキュメントや Capawesome Cloud の管理機能を利用します。