CLI オンボーディングガイド

概要

Capgo CLI は、Capacitor アプリのライブアップデートを設定するインタラクティブなオンボーディングを提供します。あなたは次のことを行うでしょう：

✅ Capgo にアプリを登録します
🔌 アップデータープラグインをインストールして構成します
🚀 最初のライブアップデートを展開する
📱 デバイスでアップデートをテストします

推定時間: 10 ～ 20 分 (インターネットの速度と構築時間によって異なります)

オンボーディングの開始

API キーを使用してオンボーディングコマンドを実行します。

npx @capgo/cli@latest init [APIKEY]

ウェルカムメッセージが表示されます。

Capgo onboarding 🛫

オンボーディング中に何が起こるか

CLI では、13 の対話型ステップを案内します。

セットアップフェーズ (ステップ 1 ～ 6):

開発環境を確認してください (Xcode/Android Studio)
アプリを Capgo に追加し、実稼働チャネルを作成します
@capgo/capacitor-updater プラグインをインストールします
必要なコードをアプリに挿入します
必要に応じてエンドツーエンド暗号化を有効にします
テスト用のプラットフォームを選択します (iOS または Android)

テスト段階 (ステップ 7 ～ 12):

アプリを構築し、デバイス/シミュレーター上で実行します。
目に見えるコード変更を行う (自動または手動)
更新されたバンドルを Capgo にアップロードします
ライブアップデートがリアルタイムでデバイスに表示されるのを確認します

完了 (ステップ 13):

アプリはライブアップデートの準備ができています。 🎉

13 ステップのオンボーディングプロセス

ステップ 1: 前提条件を確認する

CLI は開発環境をチェックして、必要なツールがインストールされていることを確認します。

チェック内容:

Xcode (macOS のみ) - iOS 開発用
Android SDK - Android 開発用

考えられる結果:

✅ 両方の環境が見つかりました:

✅ Xcode detected - iOS development ready
✅ Android SDK detected - Android development ready

⚠️ 環境が見つかりません:

⚠️ Xcode not found
⚠️ Android SDK not found
❌ No development environment detected

📱 To develop mobile apps with Capacitor, you need:
   • For iOS: Xcode (macOS only) - https://developer.apple.com/xcode/
   • For Android: Android Studio - https://developer.android.com/studio

よくある質問:

ステップ 2: アプリを追加する

CLI により Capgo にログインし、アプリがアカウントに追加されます。

(spinner) Running: npm @capgo/cli@latest login ***
Login Done ✅

❓ Add {appId} in Capgo?

アプリ ID がすでに取得されている場合:

CLI は代替案を提案します。

❌ App ID "com.example.app" is already taken
💡 Here are some suggestions:
   1. com.example.app2
   2. com.example.app3
   3. com.example.app.new
   4. com.example.app.app

❓ What would you like to do?

提案を選択するか、カスタムアプリ ID を入力できます。

ステップ 3: 本番チャネルの作成

チャネルを使用すると、アプリのさまざまな更新ストリームを管理できます。

❓ Create default channel production for {appId} in Capgo?

はいを選択した場合:

(spinner) Running: npm @capgo/cli@latest channel add production {appId} --default
Channel add Done ✅  (or "Channel already added ✅")

実稼働チャネルが作成され、デフォルトとして設定されます。これは、ほとんどのユーザーにとって推奨されるオプションです。

「いいえ」を選択した場合:

If you change your mind, run it for yourself with: "npm @capgo/cli@latest channel add production {appId} --default"

後でチャネルを手動で作成して構成する必要があります。あるいは、次のこともできます。

capacitor.config.ts ファイルにチャンネルを設定します
JavaScript setChannel() メソッドを使用してチャネルを動的に設定します
後で Capgo Web コンソールからチャネルを設定します

ステップ 4: アップデータプラグインをインストールする

CLI は、Capacitor バージョンと互換性のある @capgo/capacitor-updater プラグインをインストールします。

❓ Automatic Install "@capgo/capacitor-updater" dependency in {appId}?

バージョンの互換性:

Capacitor 5: @capgo/capacitor-updater v5 をインストールします
Capacitor 6: @capgo/capacitor-updater v6 をインストールします
Capacitor 7: @capgo/capacitor-updater v7 をインストールします
Capacitor 8+: 最新バージョンをインストールします

即時更新オプション:

インストール後、次のことを尋ねられます。

❓ Do you want to set instant updates in {appId}?
   Read more: https://capgo.app/docs/live-updates/update-behavior/#applying-updates-immediately

はいを選択した場合:

アップデートは、アプリがバックグラウンドで再度開かれたときにすぐに適用されるように構成されます
directUpdate: 'always' と autoSplashscreen: true が構成に追加されます
capacitor.config.ts は自動的に更新されます
差分アップデートが自動的に有効になります。これにより、完全なバンドルではなく、アップデートの間に変更されたファイルのみが送信されるため、アップデートが大幅に高速化されます。

「いいえ」を選択した場合:

更新は標準の動作を使用します (バックグラウンドでダウンロード、次回の再起動時に適用)
capacitor.config.ts を変更することで、後でいつでもインスタントアップデートを有効にできます。

ステップ 5: 統合コードを追加する

CLI は、必要なコードをメインアプリケーションファイルに自動的に挿入します。

❓ Automatic Add "CapacitorUpdater.notifyAppReady()" code and import in {appId}?

追加される内容:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

プロジェクトタイプの検出:

Nuxt.js: plugins/capacitorUpdater.client.ts を作成します
その他のフレームワーク: メインエントリファイルに追加します。

自動挿入が失敗した場合、メインアプリケーションファイルにコードを手動で追加できます。

Nuxt.js の場合: plugins/capacitorUpdater.client.ts を作成します。

import { CapacitorUpdater } from '@capgo/capacitor-updater'

export default defineNuxtPlugin(() => {
  CapacitorUpdater.notifyAppReady()
})

他のフレームワークの場合: メインエントリファイルに追加します (例: main.ts、index.js、App.tsx)。

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

このコードは、インポート後、アプリの初期化前に配置します。詳細については、「アプリの追加ガイド」(/docs/getting-started/add-an-app/) を参照してください。

ステップ 6: 暗号化のセットアップ (オプション)

エンドツーエンドの暗号化により、アップデートに追加のセキュリティ層が追加されます。

🔐 End-to-end encryption
   ✅ Use this for: Banking, healthcare, or apps with legal encryption requirements
   ⚠️  Note: Makes debugging harder - skip if you don't need it

❓ Enable end-to-end encryption for {appId} updates?

暗号化を有効にすると、CLI は次のようになります:

暗号化キーの生成
Capacitor 設定の同期を申し出ます

ステップ 7: プラットフォームの選択

オンボーディング中にテストするプラットフォームを選択します。

📱 Platform selection for onboarding
   This is just for testing during onboarding - your app will work on all platforms

❓ Which platform do you want to test with during this onboarding?
   Options:
   - iOS
   - Android

ステップ 8: プロジェクトを構築する

CLI はアプリを構築し、Capacitor と同期します。

❓ Automatic build {appId} with "npm run build"?

何が起こるか:

プロジェクトの種類を検出します
ビルドスクリプトを実行します
npx cap sync {platform} を実行します

ビルドスクリプトが見つからない場合:

ビルドをスキップするか、package.json にビルドスクリプトを追加するかを尋ねられます。

ステップ 9: デバイス上で実行する

デバイスまたはシミュレーターでアプリの初期バージョンをテストします。

❓ Run {appId} on {PLATFORM} device now to test the initial version?

はいを選択した場合:

(spinner) Running: npx cap run {platform}
(device picker appears)
App started ✅
📱 Your app should now be running on your {platform} device with Capgo integrated
🔄 This is your baseline version - we'll create an update next

ステップ 10: テスト変更を行う

次に、目に見える変更を加えて Capgo の更新システムをテストします。

🎯 Now let's test Capgo by making a visible change and deploying an update!

❓ How would you like to test the update?
   Options:
   - Auto: Let Capgo CLI make a visible change for you
   - Manual: I'll make changes myself

自動モード: CLI はファイルを自動的に変更して、表示されるテストバナーを追加したり、変更を加えたりします。

手動モード: 独自の変更を加えます (テキスト、色の変更、要素の追加など)。

バージョンの処理:

❓ How do you want to handle the version for this update?
   Options:
   - Auto: Bump patch version ({currentVersion} → {nextVersion})
   - Manual: I'll provide the version number

変更を加えて構築:

❓ Build {appId} with changes before uploading?

ステップ 11: バンドルをアップロードする

更新されたアプリバンドルを Capgo にアップロードします。

❓ Upload the updated {appId} bundle (v{version}) to Capgo?

CLI は次のように実行されます。

npx @capgo/cli@latest bundle upload

デルタ更新プロンプト (直接更新が有効な場合):

💡 Direct Update (instant updates) is enabled in your config
   Delta updates send only changed files instead of the full bundle

❓ Enable delta updates for this upload? (Recommended with Direct Update)

成功:

✅ Update v{version} uploaded successfully!
🎉 Your updated bundle is now available on Capgo

ステップ 12: デバイスでアップデートをテストする

アップデートが実際に行われる様子を見てみましょう!

🧪 Time to test the Capgo update system!
📱 Go to your device where the app is running

インスタントアップデートの場合:

🔄 IMPORTANT: Background your app (swipe up/press home button) and then reopen it
⏱️  The update should be downloaded and applied automatically

標準アップデートの場合:

📱 With standard updates, you will need to:
   1. Background the app (swipe up/press home button) to start download
   2. Wait a few seconds for download to complete
   3. Background and foreground again to see the update

監視ログ:

❓ Monitor Capgo logs to verify the update worked?

はいを選択すると、更新プロセスを示すライブログがデバイスから表示されます。

ステップ 13: 完了

Welcome onboard ✈️!

おめでとうございます！アプリの Capgo ライブアップデートが正常に設定されました。

あなたが達成したこと

オンボーディングが完了すると、以下が得られます。

✅ アプリが登録されました

アプリは実稼働チャネルを使用して Capgo に登録されています

✅ プラグインがインストールされています

Capacitor アップデータプラグインがインストールされ、設定されている

✅ コードの統合

統合コードがアプリに追加されます

✅ アップデートテスト済み

正常にデプロイされ、ライブアップデートを受け取りました

毎日のワークフロー

以降の更新には、次を使用します。

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

その他の展開オプションについては、「ライブアップデートの展開」(/docs/getting-started/deploy/) を参照してください。

オンボーディングの再開

オンボーディングプロセスを終了しても、いつでも再開できます。

npx @capgo/cli@latest init [APIKEY]

次のことがわかります:

You have already got to the step {stepNumber}/13 in the previous session
❓ Would you like to continue from where you left off?

トラブルシューティング

開発環境がない

問題: Xcode も Android SDK も検出されません。

解決策:

iOS の場合: Xcode をインストールします (macOS のみ)
Android の場合: Android Studio をインストールします。

アプリ ID はすでに取得されています

問題: アプリ ID はすでに登録されています。

解決策: 提案された代替案のいずれかを選択するか、逆ドメイン表記でカスタムアプリ ID を入力します。

ビルドスクリプトがありません

問題: package.json にビルドスクリプトが見つかりません。

解決策: package.json にビルドスクリプトを追加します。

{
  "scripts": {
    "build": "your-build-command"
  }
}

自動インジェクションが失敗しました

問題: CLI は統合コードを自動的に挿入できません。

解決策: コードをメインファイルに手動で追加します。

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Capacitor バージョンが古すぎます

問題: Capacitor のバージョンは v5 未満です。

解決策: Capacitor を v5 以降にアップグレードします。

次のステップ

オンボーディングが完了したので、次のトピックを検討してください。

アップデートの展開

Capgo ダッシュボードからアップデートを展開する方法を学びます

更新の種類

すべての OTA 更新タイプのリファレンス: 適用タイミング、遅延条件、バージョンブロック、および配信

CI/CDの統合

CI/CD を使用して更新プログラムのデプロイを自動化する

Channels

チャネルを使用して複数の更新ストリームを管理する

Encryption

エンドツーエンドの暗号化でアップデートを保護します

更新動作

アップデートをいつどのように適用するかをカスタマイズします (直接、デルタなど)。

助けを求める

オンボーディング中に問題が発生した場合:

[トラブルシューティングガイド]を確認してください(/docs/getting-started/troubleshooting/)
[Discordコミュニティ]に参加してください(https://discord.capgo.app)
FAQ を確認してください。
サポートに連絡してください