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

概要

Capgo CLI は、Capacitor アプリのライブアップデートをセットアップするインタラクティブなオンボーディングを提供します。以下を行います：

1. ✅ Capgo にアプリを登録
2. 🔌 updater プラグインのインストールと設定
3. 🚀 最初の live update をデプロイ
4. 📱 デバイスでアップデートをテスト

所要時間の目安： 10〜20分（通信速度やビルド時間により異なります）

ヒント

オンボーディングはいつでも再開できます。中断しても、後から続きから再開できます。

オンボーディングを開始する

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

npx @capgo/cli@latest init [APIKEY]

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

Capgo onboarding 🛫

オンボーディングの流れ

CLI が13個のインタラクティブなステップを案内します：

セットアップフェーズ（ステップ1〜6）：

• 開発環境（Xcode/Android Studio）を確認
• アプリをCapgoに追加し、本番チャネルを作成
• インストール @capgo/capacitor-updater プラグイン
• アプリに必要なcodeを注入
• エンドツーエンド暗号化を有効化（任意）
• テスト用プラットフォームを選択（iOSまたはAndroid）

テストフェーズ（ステップ7〜12）：

• アプリをビルドして、デバイス/シミュレーターで実行します
• 目に見える code の変更を加えます（自動または手動）
• 更新されたバンドルを Capgo にアップロードします
• デバイス上で live update がリアルタイムで反映されるのを確認します

完了（ステップ 13）:

• アプリはライブアップデートの準備が整いました！🎉

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

ステップ 1: 前提条件の確認

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

チェックされる項目:

• iOSプロファイリング (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

確認される可能性がある質問:

注意

開発環境が検出されない場合、続行するかどうかを尋ねられます。続行する前に、少なくとも1つのプラットフォームをインストールすることをお勧めします。

ステップ 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を入力できます。

注意

アプリIDは逆ドメイン表記に従う必要があります（例、 com.example.myapp)

ステップ 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 ✅")

本番環境用のチャネルが作成され、デフォルトに設定されます。ほとんどのユーザーにはこのオプションが推奨されます。

「No」を選択した場合：

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 ウェブコンソールからチャネルを設定する

ステップ 4: Updater Plugin のインストール

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

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

バージョン互換性:

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

注意

Capgo は Capacitor v5 以降のみサポートしています。古いバージョンを使用している場合は、先にアップグレードする必要があります。

即時更新オプション:

インストール後、次の質問が表示されます:

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

ヒント

即時更新とは? 即時更新を有効にすると、アプリがバックグラウンドに移され、再度開かれた際に即座に更新が適用されます。Capgo が世界中で 300ms 未満で更新を配信できるため、シームレスに動作します。無効の場合（標準モード）、更新はバックグラウンドでダウンロードされ、次のアプリ再起動時に適用されます。即時更新は、開発中の高速なイテレーションや本番環境での重大なバグ修正に最適です。

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

• アプリがバックグラウンドに移行して再開された時点で、更新が即座に適用されるよう設定されます
• autoUpdate: 'always' と autoSplashscreen: true 設定に追加されます
• @capacitor/splash-screen 未インストールの場合は、以下でインストールされます： launchAutoHide: false
• お使いの capacitor.config.ts 自動的に更新されます
• 差分アップデート 有効なままにします。Instant apply (always, atInstall, onLaunch）を使い続ける必要があります npx @capgo/cli@latest bundle upload --delta 変更されたファイルだけがダウンロードされるので、ユーザーがzip全体のダウンロードを待たされることはありません

「No」を選択した場合：

• アップデートは標準の動作（バックグラウンドでダウンロードし、次回の再起動時に適用）になります
• 後から自分の設定を変更すれば、いつでも instant updates を有効にできます capacitor.config.ts

ステップ 5: Code の統合を追加

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

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

追加される内容:

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

CapacitorUpdater.notifyAppReady()

プロジェクトタイプの判定:

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

ヒント

自動注入が失敗した場合は、メインのアプリケーションファイルに code を手動で追加できます：

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()

この code を import 文の後、アプリの初期化処理の前に記述してください。詳細は アプリ追加ガイド.

ステップ 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?

注意

暗号化は Capacitor v6 以降でのみ利用できます。

暗号化を有効にすると、CLI は以下を行います：

1. 暗号化キーを生成します
2. 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"?

実行される内容:

1. プロジェクトタイプの検出
2. ビルドスクリプトの実行
3. 実行します 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?

ヒント

別のターミナルで手動ビルドが必要な場合は、「No」を選択して自分でビルドしてから続行してください。

ステップ 11: Bundle のアップロード

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

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

CLI が実行します:

npx @capgo/cli@latest bundle upload

ヒント

即座に反映される Delta アップデート: ステップ4で即時アップデートを有効にしている場合、CLI がデルタアップデートを有効にするかどうかを自動的に確認します。デルタアップデートでは、バンドル全体ではなく、バージョン間で変更されたファイルだけが送信されます。通常、アップデート間で変更されるファイルは数個だけなので、ダウンロードが大幅に速くなります。選択 はい 即時アップデートを最高の体験にするために。

デルタアップデートのプロンプト（即時適用モードが有効な場合）:

💡 Instant updates are enabled in your config
   Delta updates send only changed files instead of the full bundle

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

注意

モノレポの場合は、追加のパスを指定する必要があるかもしれません。 package.json と node_modules.

成功：

✅ 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 Live Updates のセットアップが完了しました。

完了したこと

オンボーディングを完了したことで、以下の準備が整いました：

✅ アプリの登録完了

Capgo に本番チャネル付きでアプリが登録されています

✅ プラグインのインストール完了

Capacitor Updater プラグインのインストールと設定が完了しました

✅ Code の統合完了

アプリに code の連携が追加されました

✅ アップデートのテスト完了

デプロイに成功し、live update を受け取りました

日々のワークフロー

以降の更新では、次を使用します:

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

その他のデプロイオプションについてはこちら Live Update をデプロイ.

Onboarding の再開

オンボーディングを中断しても、いつでも再開できます:

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向け: インストール iOSプロファイリング (macOSのみ)
• Android向け: インストール デバッグ

App IDが既に使用されています

問題: お使いのApp IDは既に登録されています。

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

ビルドスクリプトが見つかりません

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

解決策: にビルドスクリプトを追加してください package.json:

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

自動インジェクション失敗

問題: CLI は code を自動的に注入できません。

解決策: メインファイルに code を手動で追加してください:

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

CapacitorUpdater.notifyAppReady()

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

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

解決策: Capacitor を v5 以上にアップグレードしてください:

• Capacitor 5 へのアップグレード
• Capacitor 6 へのアップグレード
• Capacitor 7 へのアップグレード

次のステップ

オンボーディングが完了したので、以下のトピックを探索してください:

初回セットアップのチェックリスト

長期的な安定性を確保するため、チャネル、CI、およびデルタアップロードを一度だけ設定します

アップデートのデプロイ

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

アップデートの種類

すべての OTA アップデートタイプの参考情報: 適用タイミング、遅延条件、バージョンブロック、配信

CI/CD 連携

CI/CDでアップデートのデプロイを自動化

チャンネル

チャンネルで複数のアップデートストリームを管理

暗号化

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

アップデートの動作

アップデートの適用タイミングと方法をカスタマイズ（direct、deltaなど）

ヘルプ・サポート

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

• チェック： トラブルシューティングガイド
• 参加して Discord コミュニティ
• 以下を確認してください: よくある質問
• お問い合わせ サポート

CLI オンボーディングガイドの続きから

使用している場合 CLI オンボーディングガイド ダッシュボードと API の運用を計画するには、これを次と連携させます API の概要 「API の概要」の実装の詳細については、 はじめに 「はじめに」における実装の詳細については、 API キー API Keys の実装の詳細については、 デバイス Devices の実装詳細については、および Bundle Bundlesの実装詳細については