ionic-enterprise-sdk-migration

Ionic Enterprise SDK の移行

提供終了となった Ionic Enterprise SDK プラグインから Capawesome の代替プラグインに、Capacitor アプリを移行します。

プラグインの対応表

Ionic Enterprise プラグイン	パッケージ	Capawesome の代替プラグイン	パッケージ
Auth Connect	@ionic-enterprise/auth	OAuth	@capawesome-team/capacitor-oauth
Identity Vault	@ionic-enterprise/identity-vault	Vault（＋ Biometrics）	@capawesome-team/capacitor-vault（＋ @capawesome-team/capacitor-biometrics）
Secure Storage（キーと値）	@ionic-enterprise/secure-storage	Secure Preferences	@capawesome-team/capacitor-secure-preferences
Secure Storage（SQLite）	@ionic-enterprise/secure-storage	SQLite	@capawesome-team/capacitor-sqlite

Capawesome の代替プラグインを使用するには、いずれも Capawesome Insiders のライセンスが必要です。

前提条件

1. Capacitor 6、7、または 8 のアプリ。
2. Node.js と npm がインストールされていること。
3. Capawesome Insiders のライセンスキー。

エージェントの動作

• 依存関係を自動検出します。 どのプラグインを移行するかユーザーに尋ねる前に、package.json をスキャンして Ionic Enterprise パッケージを確認します。
• プラグインを1つずつ移行します。 次のプラグインに着手する前に、1つのプラグインの移行を完了します。
• インストールには capacitor-plugins スキルを使用します。 プラグインのインストールとプラットフォーム設定は capacitor-plugins スキルに委任します。このスキルでは、アンインストールやコード置換など、移行固有の手順のみを扱います。
• 既存の動作を維持します。 API 呼び出しを置き換える際は、同じスコープ、保存済みキー、データベーススキーマなど、同じ機能上の動作を維持します。

MCP サーバー

Capawesome MCP サーバー は最新の Capawesome ドキュメントを提供するため、このスキルに含まれるガイダンスよりも常に新しい情報を参照できます。

• Capawesome MCP ツールを利用できる場合は、 search_docs を呼び出してトピックを検索し、get_doc_page で該当ページを読んでから、以下のガイダンスを適用してください。両者の内容が異なる場合は、ドキュメントに従ってください。
• 利用できない場合は、 以下のコマンドでサーバーを追加できることを一度だけ伝えたうえで、このスキルの手順を続けてください。サーバーの利用を必須条件にしないでください。

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

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

手順

ステップ 1：Ionic Enterprise の依存関係を検出する

package.json を読み込み、以下のパッケージがあるか確認します。

• @ionic-enterprise/auth → Auth Connect
• @ionic-enterprise/identity-vault → Identity Vault
• @ionic-enterprise/secure-storage → Secure Storage

見つからない場合は、Ionic Enterprise プラグインが検出されなかったことをユーザーに伝えます。

複数見つかった場合は、それらを一覧表示し、どれを最初に移行するかユーザーに尋ねるか、順番にすべて移行します。

ステップ 2：Capawesome npm レジストリを設定する

@capawesome-team の npm レジストリがすでに設定されているか確認します。

npm config get @capawesome-team:registry

設定されていない場合は、ユーザーにセットアップを案内します。

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

必要に応じて、ライセンスキーをユーザーに尋ねます。続行する前に確認を待ってください。

ステップ 3：各プラグインを移行する

検出された Ionic Enterprise プラグインごとに、対応するリファレンスファイルを読み、移行手順に従います。

• Auth Connect → references/auth-connect-migration.md を読みます
• Identity Vault → references/identity-vault-migration.md を読みます。コードを変更する前に、既存の保存データを保持する（移行期間中は両方のプラグインをインストールしたままにし、実行時にデータを移行する）か、一度に切り替える（古いデータを破棄して、直ちに切り替える）かをユーザーに確認します。選択した方針によって実行する手順が異なります。リファレンスファイルの方針のセクションを参照してください。
• Secure Storage → references/secure-storage-migration.md を読みます

各リファレンスファイルには、次の内容が含まれています。

1. 機能の対応表（Ionic API → Capawesome API）
2. 注意すべき主な違い
3. 変更前と変更後の例を含む、コードの置き換え手順

プラグインのインストールとプラットフォーム固有の設定（Android の権限、iOS の plist エントリー、Proguard ルールなど）には、capacitor-plugins スキルを使用します。

ステップ 4：残っている Ionic Enterprise のインポートを検索する

すべての移行が完了したら、コードベース内に Ionic Enterprise のインポートが残っていないか検索します。

grep -r "@ionic-enterprise" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx"

見つかった場合は、対応する Capawesome のインポートに置き換えます。

ステップ 5：クリーンアップと検証

1. package.json からすべての Ionic Enterprise パッケージを削除します。

npm uninstall @ionic-enterprise/auth @ionic-enterprise/identity-vault @ionic-enterprise/secure-storage

実際にインストールされていたパッケージのみをアンインストールします。

Identity Vault の例外（データ保持方針）： ユーザーが既存データの保持を選択した場合、ここでは @ionic-enterprise/identity-vault をアンインストールしないでください。古いデータをエクスポートできるのは、両方のプラグインがインストールされている間のみです。そのため、実行時のデータ移行がリリースされ、デバイス上で実行されるまで残しておき、その後のリリースで削除します（references/identity-vault-migration.md の手順 2 と 9 を参照）。一度に切り替える場合、Identity Vault は移行中にすでにアンインストールされています。

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

npx cap sync

3. すべてのプラットフォームでプロジェクトが正常にビルドされることを確認します。

エラー処理

• Capawesome レジストリが設定されていない： @capawesome-team/* パッケージの npm install が 404 または認証エラーで失敗する場合は、npm レジストリが正しく設定されていることを確認します（ステップ 2）。
• Capawesome Insiders ライセンスがない： 置き換え先のプラグインはすべて Capawesome Insiders ライセンスが必要です。ライセンスの取得先として、capawesome.io/insiders をユーザーに案内します。
• Identity Vault のセッション管理： Capawesome Vault プラグインは、lockAfterBackgrounded オプションと lock／unlock イベントリスナーによる自動ロックを標準でサポートしており、Identity Vault の lockAfterBackgrounded、onLock、onUnlock によく対応しています。カスタムパスコードの Vault に直接相当する機能はないため、アプリケーションのロジックを使って再構築する必要があります。references/identity-vault-migration.md を参照してください。
• Secure Storage の暗号化： Ionic Secure Storage には暗号化機能が組み込まれています。Capawesome SQLite の暗号化には、プラットフォームごとの追加設定（SQLCipher）が必要です。データベースの暗号化が必要な場合は、capacitor-plugins スキルのリファレンスにある SQLite 暗号化の設定手順を案内します。
• Web プラットフォームの制限： Capawesome Secure Preferences は、Web 上では値を暗号化せずに localStorage に保存します。これは開発専用であり、本番環境では使用しないでください。

関連スキル

• capacitor-plugins — プラグインのインストールとプラットフォーム設定について、このスキル内で随時参照します。
• ionic-appflow-migration — プロジェクトで Ionic Appflow（Live Updates、Native Builds、App Store Publishing）も使用している場合は、このスキルを使って Capawesome Cloud に移行します。
• capawesome-mcp — MCP クライアントをホストされた Capawesome MCP サーバーに接続し、常に最新のドキュメントと Capawesome Cloud 管理機能を利用します。