ionic-appflow-migration

Ionic Appflow の移行

プロジェクトで使用している Appflow の機能（Live Updates、ネイティブクラウドビルド、ストアへのデプロイ）をそれぞれ置き換え、各置き換えが検証できてから Appflow を削除してください。

背景：Ionic は 2025 年 2 月に Appflow の販売を終了しました。既存のお客様は新機能の提供なしで 2027 年 12 月 31 日まで利用できます。その日より十分前に移行を計画してください。

使用するタイミング

次の場合に使用します：

• package.json に @capacitor/live-updates または cordova-plugin-ionic がある。
• capacitor.config.* に plugins.LiveUpdates がある、または config.xml／Info.plist／strings.xml に Appflow のデプロイキー（APP_ID、CHANNEL_NAME、UPDATE_METHOD、IonAppId、IonChannelName）がある。
• CI から ionic deploy、appflow、ionic package build が呼び出されている、または Appflow ダッシュボードがビルドやストアへのアップロードをトリガーしている。

次の場合には使用しないでください：

• @ionic-enterprise/* プラグイン → ionic-enterprise-sdk-migration。
• Capawesome Cloud → capawesome-live-update-migration。
• 新規の Capgo セットアップ → capgo-live-updates。

稼働中のプロジェクトのスナップショット

検出された Appflow 関連のパッケージとスクリプト： !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name==='@capacitor/live-updates'||name==='cordova-plugin-ionic'||name.includes('appflow')||name==='@ionic/cli'||name==='@capgo/capacitor-updater'||name==='@capacitor/core')out.push(section+'.'+name+'='+version)}}for(const [name,cmd] of Object.entries(pkg.scripts||{})){if(/appflow|ionic deploy|ionic package|live-updates/i.test(cmd))out.push('scripts.'+name+'='+cmd)}console.log(out.join('\n'))"

Appflow の設定とワークフローが存在する可能性のあるパス： !find . -maxdepth 4 -not -path '*/node_modules/*' \( -name '.io-config.json' -o -name 'ionic.config.json' -o -name 'config.xml' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' -o -path './.github/workflows/*' -o -name '.gitlab-ci.yml' -o -name 'appflow.config.json' \)

手順

ステップ 1：棚卸し（編集前に報告）

rg -n "@capacitor/live-updates|cordova-plugin-ionic|LiveUpdates|IonAppId|IonChannelName|UPDATE_METHOD|CHANNEL_NAME|ionic deploy|appflow|dashboard.ionicframework.com|ionic.io/appflow" \
  -g '!node_modules' .

機能ごとに記録します：

• Live Updates：使用中の SDK、Appflow のアプリ ID、チャンネルと、それらを参照するバイナリ、更新方法（background、none、再開時に常に最新、強制更新）、maxVersions、sync()、download()、extract()、reload() を呼び出すコードの有無。
• ネイティブビルド：ビルドスタック、Appflow に保存されている署名証明書／プロファイルとキーストア、環境変数、ネイティブ設定のオーバーライド。
• ストアへのデプロイ：TestFlight／Play の配信先とトラック。

Appflow で署名資格情報を削除する前に、Appflow からエクスポートする（または元の資格情報を保有していることを確認する）ようユーザーに依頼してください。

手順 2：ライブアップデート → Capgo

npm uninstall @capacitor/live-updates   # or: npm uninstall cordova-plugin-ionic
npm install @capgo/capacitor-updater
npx cap sync

cordova-plugin-ionic の場合は、config.xml から <plugin>／<variable> のエントリーと、ネイティブファイルから Ion* キーも削除します。

設定ブロックを置き換えます。

// capacitor.config.ts
plugins: {
  // remove LiveUpdates: { appId, channel, autoUpdateMethod, maxVersions }
  CapacitorUpdater: {
    autoUpdate: true,
    autoDeletePrevious: true,
  },
},

Appflow	Capgo
appId	npx @capgo/cli@latest init で作成した Capgo アプリ（capacitor.config の appId を使用）
channel	Capgo チャネル（ダッシュボード／CLI）。デフォルトチャネルはサーバー側で設定するか、ビルドごとに上書きする場合は設定で defaultChannel を指定します
autoUpdateMethod: 'background'	autoUpdate: true（デフォルトの動作：バックグラウンドでダウンロードし、次回起動時に適用）
autoUpdateMethod: 'none' + 手動の sync()	製品で独自のタイミングが必要な場合を除き、autoUpdate: true を維持します。それ以外の場合は autoUpdate: false と手動 API を使用します
maxVersions	autoDeletePrevious: true とサーバー側のバンドル保持を組み合わせます
バイナリバージョンによるターゲティング	ネイティブのメジャーバージョンごとにチャネルを設定するか、--min-update-version ／メタデータ戦略（capgo-release-workflows）を使用します
強制アップデート	Capgo でバンドル／チャネルの動作を設定し、majorAvailable をリッスンするか、directUpdate を使用します

アプリのシェルがレンダリングされたら、必須のフックを一度追加します。

import { CapacitorUpdater } from '@capgo/capacitor-updater';
void CapacitorUpdater.notifyAppReady();

これがないと、Capgo はバンドルを破損していると判断し、ロールバックします。

API の対応関係（製品で独自の UI やタイミングが必要な場合に限り、手動呼び出しを維持します）：

Appflow（@capacitor/live-updates）	Capgo
LiveUpdates.sync()	autoUpdate: true の場合は不要です。手動で行う場合は CapacitorUpdater.getLatest() + download() を使用します
LiveUpdates.reload()	CapacitorUpdater.set({ id })（適用して再読み込み）または reload()
sync() を呼び出す resume リスナー	削除します。再開時のアップデート確認は自動で行われます
sync 後の SplashScreen.hide()	アプリの起動後に通常の SplashScreen.hide() を呼び出します。必要に応じて appReady リスナーを使用します

最初のバンドルをテストチャネルにアップロードします。

npm run build
npx @capgo/cli@latest bundle upload --channel development

手順 3：ネイティブのクラウドビルド

置き換え方法は 2 つあります。どちらを希望するかユーザーに確認してください。

• Capgo Cloud Build：npx @capgo/cli@latest build credentials save --platform ios|android ... を実行し、その後 npx @capgo/cli@latest build request <appId> --platform ios|android を実行します。詳細は capgo-native-builds を参照してください。
• リポジトリ所有の CI（GitHub Actions、GitLab、Fastlane）：capacitor-ci-cd を使用します。

環境変数、ビルド時の設定、署名用の入力値はそのまま引き継ぎ、変更は一度に 1 つにします。

手順 4：ストアへの公開

Capgo Cloud Build では、ストアの認証情報を保存していれば TestFlight ／ Play にアップロードできます。そうでない場合は、CI のアップロード手順（capacitor-ci-cd）または手動での申請（capacitor-app-store）を使用します。バンドル ID、Play のトラック、認証情報は変更しないでください。

手順 5：切り替えとクリーンアップ

1. @capgo/capacitor-updater を含むネイティブビルドをストアにリリースします。古いバイナリを使用しているデバイスは、アップデートするまで Appflow から取得し続けます。移行が十分に進むまで、Appflow チャネルを有効にしておいてください。
2. 移行期間中は両方のシステムに Web アップデートを公開するか、新しいバイナリに含まれる最後のバンドルで Appflow を凍結します。
3. サポート対象のバイナリが Appflow に依存しなくなったら、Appflow パッケージ、plugins.LiveUpdates、.io-config.json の参照、Appflow の CI ジョブ、シークレットを削除します。

検証

• rg -n "@capacitor/live-updates|cordova-plugin-ionic|LiveUpdates\\." -g '!node_modules' . の実行結果が、クリーンアップ後に空であることを確認します。
• 新しいバイナリを新規インストールし、ログで notifyAppReady が呼び出されたことを確認します。Capgo ダッシュボードにデバイスが表示されることを確認します。
• テスト用の非本番チャネルにテストバンドルをアップロードします。デバイスがダウンロードし、次回起動時に適用することを確認します。
• 意図的に壊したバンドル（notifyAppReady なし）をテストチャネルにアップロードします。デバイスがロールバックすることを確認します。
• 新しいネイティブビルドパイプラインで、同じバンドル ID とより大きなビルド番号を持つ、署名済み IPA ／ AAB が生成されることを確認します。

エラー処理

問題	解決方法
アプリが更新のたびにロールバックする	notifyAppReady() に到達していません（呼び出しが遅すぎる、ログイン処理の後にある、またはコードパスで例外が発生している）。シェルがレンダリングされた直後に呼び出してください
Capgo CLI で Cannot find API key in local folder or global, please login first が表示される	ローカルで npx @capgo/cli@latest login <apikey> を実行するか、CI で CAPGO_TOKEN を設定してください
更新が届かない	デバイスがバンドルのないチャンネルを使用しているか、バンドルがネイティブバージョンと互換性がありません。チャンネルを確認し、npx @capgo/cli@latest bundle compatibility を実行してください
古い Appflow の更新によって Capgo バンドルが上書きされる	バイナリに古い SDK がまだインストールされています。ビルド前に @capacitor/live-updates / cordova-plugin-ionic が削除され、npx cap sync が実行されていることを確認してください
Appflow の削除後にビルドが失敗する	Appflow が環境変数またはネイティブ設定を注入していました。CI または Capgo Cloud Build 環境で再作成してください