capacitor-plugins

Capacitor プラグイン

適切なプラグインを選び、正しくインストールし、ネイティブにリンクされていることを確認します。

使用する場合

次の場合に使用します。

• ユーザーが「X にはどのプラグインを使えばよいですか？」と質問する、またはプラグインの選択肢を比較する場合。
• カメラ、ファイル、位置情報、生体認証、決済、認証、センサー、ストレージ、メディア、カレンダー、連絡先、ヘルスケア、オンデバイス LLM などのネイティブ機能が必要な場合。
• インストール後にプラグインの呼び出しが失敗する場合："X" plugin is not implemented on ios|android|web、UNIMPLEMENTED、unable to find plugin、または OS-PLUG-* コード。
• プラグインに必要な Info.plist／AndroidManifest.xml／variables.gradle のエントリが必要な場合。

使用しないでください（代わりに関連するスキルを読み込みます）。

• プッシュ通知の設定、FCM/APNs キー：capacitor-push-notifications
• スプラッシュ画面のアセットと表示タイミング：capacitor-splash-screen
• キーボードとの重なり、アクセサリーバー、リサイズ：capacitor-keyboard
• Universal Links／App Links：capacitor-deep-linking
• OTA ライブアップデート：capgo-live-updates
• プラグインのソースコードを Capacitor のメジャーバージョン間で移行する場合：capacitor-plugin-upgrades（および capacitor-plugin-upgrade-v8-to-v9）
• プラグインに Swift Package Manager のサポートを追加する場合：capacitor-plugin-spm-support、アプリを SPM に移行する場合：cocoapods-to-spm
• AppDelegate／SceneDelegate のライフサイクル変更：capacitor-uiscene-migration
• アプリの Capacitor メジャーバージョンをアップグレードする場合：capacitor-app-upgrades
• SQL ストレージの移行：sqlite-to-fast-sql

バージョン情報（2026年10月）

• Capacitor の安定版：8.5.x（latest）。Capacitor 9 は next dist-tag の 9.0.0-alpha です。公式プラグインもこれに準じます。v8 のプラグインの多くは latest で 8.x、next で 9.0.0-alpha です。
• プラグインのメジャーバージョンは、アプリの Capacitor メジャーバージョンに合わせる必要があります。旧メジャーバージョン向けのプラグインには latest-<major> タグを使います。例：npm install @capacitor/camera@latest-7。
• 一部の公式プラグインは独自のバージョン体系です（file-transfer 2.x、file-viewer 2.x、inappbrowser 4.x、privacy-screen 2.x、barcode-scanner 3.x、background-runner 3.x、calendar/contacts/health-fitness 1.x）。バージョン番号を合わせるのではなく、npm view <pkg> peerDependencies を確認してください。
• @capgo/* プラグインは、Capacitor のメジャーバージョンを独自のメジャーバージョンとして使用します（Capacitor 8 では 8.x）。一部のパッケージには lts-v7 などの LTS タグがあります。
• Capacitor 9：iOS の最小バージョンは 16、Android の minSdk は 26 です。以前は minSdkVersion = 26 が必要だったプラグイン（inappbrowser、barcode-scanner）も、minSdk の引き上げが不要になります。

手順

1. まず確認します。 package.json（@capacitor/core のバージョン）と capacitor.config.* を読み、iOS が SPM（ios/App/CapApp-SPM/Package.swift）と CocoaPods（ios/App/Podfile）のどちらを使用しているか確認します。npx cap ls を実行し、すでにリンクされているものを確認します。

2. パッケージを選びます。

   • 要件を満たす公式の @capacitor/* パッケージがある場合は、それをデフォルトで選びます。以下のインデックスから該当するリファレンスを読み込みます。
   • 公式パッケージがない、または必要な機能が不足している場合は、references/capgo-plugin-index.md を読み込み、該当する @capgo/* の名前を選びます。より適している理由も説明します。
   • リファレンスファイルに記載されていないパッケージ名を推奨する場合は、先に npm view <pkg> version で確認してください。

3. メジャーバージョンを合わせてインストールします。

   npm install @capacitor/<name>        # or @capgo/<name>
   npx cap sync
   

4. リファレンスに基づいてネイティブ設定を追加します。 使用目的の説明キー、マニフェストの権限、variables.gradle の minSdk／ライブラリバージョン、Capabilities／Entitlements、AppDelegate のフックを追加します。iOS の使用目的文字列がないと、初回アクセス時にアプリがクラッシュします。

5. ユーザーに確認します。 minSdkVersion の引き上げ、Entitlements（HealthKit、Push）の追加、または正確なアラームの有効化を行う前に確認してください。これらはストア審査とデバイスへの対応範囲に影響します。

6. 確認します（次のセクション）。続いて、カメラ、ヘルスケア、LLM、BLE、プッシュに関わるものは、実機で実行します。

Capgo プラグインインデックス

references/capgo-plugin-index.md は、Cap-go GitHub の package.json と src/definitions.ts から生成された、Capgo プラグインの完全なソースです。公開済みでアーカイブされていない各パッケージについて、npm 名、用途、インストールコマンド、プラットフォーム、主要な API メソッド、ドキュメントおよびリポジトリへのリンクが記載されています。references/capgo-plugin-catalog.md は、同じ内容をコンパクトな表にまとめたものです。@capgo/* パッケージを推奨する前にインデックスを読み込み、記載されている正確な名前を使用してください。

Cap-go の組織に変更があった場合は、両方を再生成してください（リポジトリのメンテナーのみ）：

GITHUB_TOKEN=$(gh auth token) node scripts/generate-capgo-plugin-index.mjs

検証

npx cap sync              # must finish without "[error]" lines
npx cap ls                # lists "Found N Capacitor plugins for ios/android"; plugin must appear for each platform

• Android：android/app/capacitor.build.gradle に implementation project(':capacitor-<name>') が含まれ、android/capacitor.settings.gradle に対応する include があることを確認します。その後、cd android && ./gradlew assembleDebug を実行します。
• iOS SPM：ios/App/CapApp-SPM/Package.swift にプラグインパッケージが記載されていることを確認します。iOS CocoaPods：ios/App/Podfile に pod が記載され、pod install が成功していることを確認します。Xcode でビルドするか、npx cap run ios を実行します。
• プラグインを置き換える際は、残りがないか grep で確認します：grep -rn "<old-package>" src android ios package.json。
• 実行時に機能を検出します：Capacitor.isPluginAvailable('Camera') と Capacitor.getPlatform()。

エラー処理

エラー	原因	修正方法
"Camera" plugin is not implemented on ios（または android／web）	ネイティブ側がリンクされていない、または Web 実装がない	npx cap sync を実行し、ネイティブアプリを再ビルドします（ライブリロードでは新しいネイティブコードは反映されません）。npx cap ls を確認します。Web では Capacitor.isNativePlatform() でガードします。
"Camera.takePhoto()" is not implemented on ios	プラグインはリンクされていますが、JS とネイティブのバージョンが異なるか、メソッドがプラットフォーム固有です	JS とネイティブのバージョンを揃え、npx cap sync を実行してからクリーンビルドします。プラットフォーム限定のメソッドについてはリファレンスを確認します。
UNIMPLEMENTED エラーコード	このプラットフォーム／OS バージョンではメソッドを利用できません	プラットフォームに応じて分岐します。リファレンスの「Notes」を参照してください。
Android のログ unable to find plugin : X	プラグインクラスが登録されていない、または含まれていません	capacitor.build.gradle のエントリーを確認し、再同期してから、Android Studio で Gradle を同期します。
iOS のログ Error loading plugin X for call. Check that the pluginId is correct	プラグインが iOS ビルドに含まれていません	再同期し、Package.swift（SPM）または Podfile を確認して、ビルドフォルダーをクリーンアップします。
iOS でカメラ／連絡先／カレンダー／位置情報への初回アクセス時にアプリがクラッシュする	NS*UsageDescription キーがありません	リファレンスに記載されているキーを Info.plist に追加します。
Manifest merger failed : uses-sdk:minSdkVersion 24 cannot be smaller than version 26 declared in library [...]	プラグインがより高い minSdk を必要としています	まずユーザーに確認してから、android/variables.gradle の minSdkVersion を引き上げます。
OS-PLUG-* コード（例：OS-PLUG-CAMR-0003）	OutSystems ベースの公式プラグインで発生する、構造化されたネイティブエラーです	プラグインリファレンスでコードを調べます（camera、file-transfer、calendar、contacts には一般的なコードが記載されています）。
npm の ERESOLVE peer @capacitor/core 競合	プラグインのメジャーバージョンがアプリのメジャーバージョンと一致していません	一致するタグ（@latest-7、または v9 alpha の場合は @next）をインストールするか、capacitor-app-upgrades でアプリをアップグレードします。

リファレンス一覧

プラグインを使用する場合にのみ、リファレンスを読み込んでください。

公式の @capacitor/* パッケージ（インストール、ネイティブ設定、使い方、注意点）：

必要な機能	リファレンス
アクションシート	references/capacitor-action-sheet.md
他のアプリを開く／インストール済みか確認する	references/capacitor-app-launcher.md
アプリの状態、戻るボタン、URL のオープンイベント	references/capacitor-app.md
バックグラウンドでの JS タスク	references/capacitor-background-runner.md
バーコード／QR コードのスキャン	references/capacitor-barcode-scanner.md
OAuth に安全なアプリ内ブラウザー（SFSafariViewController／Custom Tabs）	references/capacitor-browser.md
カレンダーのイベント	references/capacitor-calendar.md
カメラ、ギャラリー、動画（8.1+ API、getPhoto の移行）	references/capacitor-camera.md
クリップボード	references/capacitor-clipboard.md
連絡先	references/capacitor-contacts.md
ネイティブ Cookie（コア）	references/capacitor-cookies.md
デバイス情報／ID／バッテリー	references/capacitor-device.md
ネイティブのアラート／確認／プロンプト	references/capacitor-dialog.md
進捗状況付きのアップロード／ダウンロード	references/capacitor-file-transfer.md
ドキュメントを開く／プレビューする	references/capacitor-file-viewer.md
ファイルの読み取り／書き込み	references/capacitor-filesystem.md
位置情報（フォアグラウンド）	references/capacitor-geolocation.md
Google Maps	references/capacitor-google-maps.md
HealthKit／Health Connect	references/capacitor-health-fitness.md
ハプティクス	references/capacitor-haptics.md
ネイティブ HTTP（コア、CORS の回避）	references/capacitor-http.md
WebView／システム／外部ブラウザー	references/capacitor-inappbrowser.md
キーボード API の基本	references/capacitor-keyboard.md
デバイス上の LLM（実験的）	references/capacitor-local-llm.md
ローカル通知	references/capacitor-local-notifications.md
加速度計／向き	references/capacitor-motion.md
接続状況	references/capacitor-network.md
キー／値ストレージ	references/capacitor-preferences.md
アプリスイッチャーのスナップショットを非表示にする／スクリーンショットをブロックする	references/capacitor-privacy-screen.md
プッシュ API の概要	references/capacitor-push-notifications.md
画面の向きをロックする	references/capacitor-screen-orientation.md
TalkBack／VoiceOver の状態、TTS	references/capacitor-screen-reader.md
共有シート	references/capacitor-share.md
スプラッシュ API の概要	references/capacitor-splash-screen.md
ステータスバー（レガシー）	references/capacitor-status-bar.md
エッジツーエッジのシステムバー（コア、Android 16+ で推奨）	references/capacitor-system-bars.md
WebView のテキストズーム	references/capacitor-text-zoom.md
トースト	references/capacitor-toast.md
Apple Watch UI（実験的）	references/capacitor-watch.md

Capgo プラグイン：references/capgo-plugin-index.md（145 パッケージ：インストール、プラットフォーム、主要 API、ドキュメント）および references/capgo-plugin-catalog.md（簡潔な一覧表）。

Capgo のおすすめ

ニーズ	パッケージ
バックグラウンドでの位置情報取得、ジオフェンシング	@capgo/background-geolocation
カスタムカメラプレビュー／オーバーレイ	@capgo/camera-preview
生体認証ログイン＋セキュアな認証情報	@capgo/capacitor-native-biometric
Apple／Google／Facebook でのサインイン	@capgo/capacitor-social-login
サブスクリプション／IAP	@capgo/native-purchases（収益化戦略：subscription-app-revenue）
Apple Pay／Google Pay	@capgo/capacitor-pay
高速なネイティブ SQLite	@capgo/capacitor-fast-sql
ネイティブのファイル操作／ファイル選択	@capgo/capacitor-file、@capgo/capacitor-file-picker
JS インジェクション、postMessage、スクリーンショットに対応したアプリ内ブラウザー	@capgo/capacitor-inappbrowser
バックグラウンドで終了した WebView の再起動	@capgo/capacitor-webview-guardian
App Attest／Play Integrity	@capgo/capacitor-app-attest
OTA ライブアップデート	@capgo/capacitor-updater（セットアップ：capgo-live-updates）
開発時のライブリロード	@capgo/capacitor-live-reload

注意点：

• 同じネイティブ機能を担うプラグイン（例：アプリ内ブラウザーが2つ、または生体認証プラグインが2つ）を、理由なく2つインストールしないでください。デリゲートやマニフェストのエントリーで競合する可能性があります。
• Firebase：個別の @capgo/capacitor-firebase-* パッケージをインストールしてください。npm に @capgo/capacitor-firebase という統合パッケージはありません。
• Cordova プラグインは引き続き動作しますが、Capacitor 9 では Cordova ランタイムが追加されます。代わりに Capacitor ネイティブの同等プラグイン（cordova-to-capacitor）を優先してください。

リソース

• 公式プラグインのドキュメント：https://capacitorjs.com/docs/apis
• Capgo プラグインのドキュメント：https://capgo.app/docs/plugins/
• Capgo の GitHub：https://github.com/Cap-go