バージョン対象

このガイドでは、ユーザーのネイティブアプリのバージョンに基づいて、最新の互換性のあるバンドルを自動的にユーザーに提供する方法を説明します。 Ionic AppFlowのアプローチと似ています。。 これにより、簡素化された更新管理と高速なロールアウトが実現され、互換性の問題が防止されます。

Ionic AppFlowから移行する場合

Ionic AppFlowから来た場合は、このガイドは特に重要です。 AppFlowは自動的に更新をネイティブバージョンにマッチさせており、Capgoは同じ機能を提供し、より多くの制御と柔軟性を提供します。 以下の AppFlowの移行ガイド を参照してください。

概要

Capgoのバージョン対象システムは、次の機能を提供します。

• 互換性のある更新を自動的に提供する ユーザーに、nativeアプリのバージョンに基づいて更新を提供します。
• 破壊的な変更を防ぎます。 非互換のアプリバージョンに到達する更新を防ぎます。
• 複雑なロジックなしで複数のアプリバージョンを管理します。 複数のアプリバージョンに対して同時に更新を提供します。
• 特定のユーザーセグメントに更新を提供します。 バージョン対象化の重要性（特にAppFlowユーザー向け）

バージョン対象化の重要性（特にAppFlowユーザー向け）

Ionic AppFlow 、ユーザーが互換性のある更新を受け取ることを保証することは非常に重要です。AppFlowは、live update bundlesをnativeアプリのバージョンに自動的にマッチさせ、古いnative __CAPGO_KEEP_0__に互換性のないJavaScriptが配信されるのを防ぎました。, you know how critical it is to ensure users receive only compatible updates. AppFlow automatically matched live update bundles to native app versions, preventing incompatible JavaScript from being delivered to older native code.

Capgoは同じ安全性の保証を提供します, 付加機能が含まれます:

• バージョンマッチングのより細かい制御
• 複数の戦略（チャネル、semver、ネイティブ制約）
• バージョン分布のよりよい視覚化
• APIとCLIはダッシュボード管理とともに制御されます

このアプローチは、特に以下の場合に便利です:

• ユーザーがアプリの異なるメジャーバージョン (例：v1.x、v2.x、v3.x) にある場合
• 破壊的な変更をロールアウトする際にバックワード互換性を維持する必要がある場合
• 新しいバンドルが古いネイティブcodeを破壊しないようにする場合
• ユーザーを一つのバージョンから別のバージョンに段階的に移行する場合
• AppFlowから移行する場合 と同様の更新の安全性を維持したい

How It Works

Capgo uses a multi-layered approach to match users with compatible updates:

1. 「Capgo Builder / Native Cloud Build」の「How It Works」__CAPGO_KEEP_0__は、ユーザーに互換性のある更新をマッチングするために、複数のレイヤーを使用します:
2. ネイティブバージョン制約: 不適合なネイティブバージョンにバンドルを配信しない
3. チャンネルベースのルーティング: 異なるアプリバージョンを異なる更新チャンネルにルーティングする
4. シーケンスバージョン制御: メジャー/マイナ/パッチ境界を自動的にブロックする更新を制御する

バージョンマッチングフロー

graph TD
    A[User Opens App] --> B{Check Device Override}
    B -->|Override Set| C[Use Override Channel]
    B -->|No Override| D{Check local plugin channel}
    D -->|setChannel value| E[Use local setChannel channel]
    D -->|No local channel| F{Check defaultChannel in App}
    F -->|Has defaultChannel| G[Use App's defaultChannel]
    F -->|No defaultChannel| H[Use Cloud Default Channel]
    C --> I{Check Version Constraints}
    E --> I
    G --> I
    H --> I
    I -->|Compatible| J[Deliver Update]
    I -->|Incompatible| K[Skip Update]

チャンネルベースのバージョンルーティング戦略1

この 推奨アプローチ メジャーバージョンアップデートや破壊的変更を管理するために使用される

アプリフローの配信モデルに似ています。

• 例シナリオのセクション アプリv1.x (100,000ユーザー) → production チャンネル
• App v2.x (50,000ユーザーに破壊的な変更を含む) → v2 チャンネル
• App v3.x (10,000のベータユーザー) → v3 チャンネル

実装

ステップ 1: 各主バージョン用にチャンネルを設定する

// capacitor.config.ts for version 1.x builds
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'production', // or omit for default
    }
  }
};

export default config;

// capacitor.config.ts for version 2.x builds
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'v2', // Routes v2 users automatically
    }
  }
};

// capacitor.config.ts for version 3.x builds
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'v3', // Routes v3 users automatically
    }
  }
};

ステップ 2: チャンネルを作成

# Create channels for each major version
npx @capgo/cli channel create production
npx @capgo/cli channel create v2
npx @capgo/cli channel create v3

# Enable self-assignment so apps can switch channels
npx @capgo/cli channel set production --self-assign
npx @capgo/cli channel set v2 --self-assign
npx @capgo/cli channel set v3 --self-assign

ステップ 3: バージョンに特化したパッケージをアップロード

# For v1.x users (from v1-maintenance branch)
git checkout v1-maintenance
npm run build
npx @capgo/cli bundle upload --channel production

# For v2.x users (from v2-maintenance or main branch)
git checkout main
npm run build
npx @capgo/cli bundle upload --channel v2

# For v3.x users (from beta/v3 branch)
git checkout beta
npm run build
npx @capgo/cli bundle upload --channel v3

自動ルーティング

アプリを開くと、自動的に指定されたチャンネルに接続されます。 defaultChannel in their installed app bundle. No JavaScript code changes required!

インストールされているアプリのバンドル内の情報に基づいて。

• Zero code changes ゼロの変更
• - チャンネルルーティングは自動的に行われます。 - 各バージョンには独自のアップデートパイプラインがあります。
• - 特定のバージョングループにアップデートをプッシュできます。 - 不相応のバージョンに破壊的な変更は届きません。
• __CAPGO_KEEP_0__ __CAPGO_KEEP_0__

戦略2：セマンティックバージョニング制御

Capgoの組み込み セマンティックバージョニング制御 バージョン境界を超えた更新を防止します。

メジャーバージョンを跨いだ自動更新を無効化

# Create a channel that blocks major version updates
npx @capgo/cli channel create stable --disable-auto-update major

アプリケーション版のユーザー

• はバージョン 1.2.3 までの更新を受け取ります。 1.9.9
• ユーザーは NO バージョン 2.0.0 自動的に
• 古いネイティブ code に破壊的な変更が到達するのを防ぐ
• ネイティブの基準として送信されたものを使用する version_build

詳細な制御オプション

# Block target bundles outside the native major.minor line (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block target bundles outside the exact native MAJOR.MINOR.PATCH core (1.2.3 won't get 1.2.4)
npx @capgo/cli channel set stable --disable-auto-update patch

# Allow all updates
npx @capgo/cli channel set stable --disable-auto-update none

シームレスなバージョニングが必要

この戦略は、以下の条件を満たす場合にのみ機能します。 アプリのバージョン管理 (semver) を実行する必要があります。 アプリのバージョン番号は、以下の形式でなければなりません。 MAJOR.MINOR.PATCH 戦略 3: ネイティブ バージョン制約

セクション “戦略 3: ネイティブ バージョン制約”

) を指定することで、__CAPGO_KEEP_0__ は、ネイティブ バイナリが最新のものであるデバイスにのみ配信されます。min_update_version) on each bundle so Capgo only delivers it to devices whose native binary is new enough.

メタデータ 戦略 ( ) を使用します。--disable-auto-update metadataプラス --min-update-version または --auto-min-update-version __CAPGO_KEEP_0__ --native-version CLI flag.

チャンネルでメタデータターゲットを有効にする

# one-time: require min_update_version metadata on uploads to this channel
npx @capgo/cli@latest channel set production --disable-auto-update metadata

最低のネイティブバージョンをアップロード時に設定する

ターミナル画面

# This bundle requires native version 2.0.0 or higher
npx @capgo/cli@latest bundle upload \
  --channel production \
  --min-update-version "2.0.0"

またはCapgoがネイティブパッケージの互換性からフロアを設定します:

npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

どうやって機能するか

バージョン対象version_build互換性 min_update_version 詳細 使用例 使用例 --auto-min-update-version 使用例

使用例

1. 新しいネイティブ プラグインが必要

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "2.0.0"

2. ネイティブの重大なAPI変更

   # Bundle uses new Capacitor 6 APIs
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "3.0.0"

3. 段階的な移行

   # one-time: enable metadata gating on beta
   npx @capgo/cli@latest channel set beta --disable-auto-update metadata
   
   # Test bundle only on latest native version
   npx @capgo/cli@latest bundle upload \
     --channel beta \
     --min-update-version "2.5.0"

自動ダウングレード防止の戦略4

最新バージョンを優先する

チャンネル設定で有効

Capgo ダッシュボードで

1. Go to チャンネル チャンネル
2. → チャンネルを選択 有効
3. 「ネイティブの自動ダウングレードを無効にする」

Or via CLI:

npx @capgo/cli@latest channel set production --no-downgrade

例

• ユーザーのデバイス:ネイティブ版 1.2.5
• チャンネルパッケージ:バージョン 1.2.3
• 結果: ダウングレードとなるため、更新はブロックされます

これは、次のような場合に便利です:

• ユーザーがアプリストアから新しいバージョンを手動でインストールした場合
• ユーザーが最新のセキュリティパッチを保証したい場合
• バグのリグレッションを防止したい場合

デバイスレベルターゲティングの戦略5

特定のデバイスまたはユーザーグループのチャネル割り当てをオーバーライドします。

テスト用に特定のバージョンを強制する

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

// Force beta testers to use v3 channel
async function assignBetaTesters() {
  const deviceId = await CapacitorUpdater.getDeviceId()

  // Check if user is beta tester
  if (isBetaTester(userId)) {
    await CapacitorUpdater.setChannel({ channel: 'v3' })
  }
}

ダッシュボードデバイスオーバーライド

Capgo ダッシュボードで

1. Go to デバイス → デバイスを検索
2. クリック チャンネルを設定 または チャンネルを選択してください
3. バージョンをオーバーライド
4. デバイスはオーバーライドされたソースからアップデートを受け取ります

テストアップデート

デバイスのオーバーライドを使用して、すべてのユーザーにロールアウトする前に、自分のデバイスでアップデートをテストしてください。

完全なAppFlowスタイルのワークフロー

ここでは、すべての戦略を組み合わせた完全な例を紹介します。

1. 初期設定 (App v1.0.0)

# Create production channel, then enable metadata min-version gating
npx @capgo/cli@latest channel add production
npx @capgo/cli@latest channel set production \
  --disable-auto-update metadata \
  --no-downgrade

capacitor.config.ts

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'production',
    }
  }
};

2. リリースブレーク変更 (App v2.0.0)

# Create v2 channel for new version
npx @capgo/cli@latest channel add v2
npx @capgo/cli@latest channel set v2 \
  --disable-auto-update metadata \
  --no-downgrade \
  --self-assign

# Create git branch for v1 maintenance
git checkout -b v1-maintenance
git push origin v1-maintenance

// capacitor.config.ts for v2.0.0
const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. 両方のバージョンにアップデートをプッシュする

# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli@latest bundle upload \
  --channel production \
  --min-update-version "1.0.0"

# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli@latest bundle upload \
  --channel v2 \
  --min-update-version "2.0.0"

4. バージョン分布の監視

Capgo ダッシュボードを使用して、以下を追跡します。

• バージョン v1 と v2 のユーザー数
• バージョンごとのバンドル採用率
• バージョンごとのエラーまたはクラッシュ数

5. 旧バージョンの非推奨

v1 の使用率が閾値以下の場合:

# Stop uploading to production channel
# Optional: Delete v1 maintenance branch
git branch -d v1-maintenance

# Move all remaining users to default
# (They'll need to update via app store)

チャネル順位

複数のチャネル設定が存在する場合、Capgoは次の順位順に使用します。

1. デバイスオーバーライド (ダッシュボードまたはAPI) - 最高優先度でデバイスオーバーライドUIに表示
2. ローカルプラグインチャネル via setChannel() - デバイス上のみ保存され、デバイスオーバーライドUIに表示されません。
3. defaultChannel capacitor.config.ts
4. デフォルトチャネル (Cloudflare設定) - 最低優先度

優先度の例

ユーザーのアプリが defaultChannel: 'v2' ですが、ユーザーのデバイスを 'beta' ダッシュボードで設定した場合、チャンネルからアップデートを受け取ることになります。 'beta' デバイスのオーバーライドUIは、ダッシュボードまたはPublic __CAPGO_KEEP_0__から設定されたオーバーライドのみを表示します。デバイス上で

The Device Override UI only lists overrides set from the dashboard or Public API. Calling setChannel() ベストプラクティス

セクションのタイトルは「ベストプラクティス」

2.

// ✅ Good: Each major version has explicit channel
// v1.x → production
// v2.x → v2
// v3.x → v3

// ❌ Bad: Relying on dynamic channel switching
// All versions → production, switch manually

2. セマンティックバージョニングを使用する

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. 分離されたブランチを維持する

# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)

# ❌ Bad: Single branch for all versions

4. リリース前にテストする

# one-time: create beta and enable metadata gating
# (production is set up in the complete workflow above)
npx @capgo/cli@latest channel add beta
npx @capgo/cli@latest channel set beta --disable-auto-update metadata

# Test on beta channel first
npx @capgo/cli@latest bundle upload \
  --channel beta \
  --auto-min-update-version

# Monitor for issues, then promote to production
npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

5. バージョン分布の監視

ダッシュボードを定期的に確認してください：

• ユーザーが最新のネイティブバージョンにアップグレードしていますか?
• 古いバージョンが高トラフィックを受けているのはなぜですか?
• 古いチャンネルを非推奨化するべきですか?

Ionic AppFlowとの比較

チームがIonic AppFlowから移行している場合 Ionic AppFlow、ここではCapgoのバージョン対象化の比較方法について説明します。

機能	イオニック アプリフロー	Capgo
バージョンベースのルーティング	ネイティブバージョンに基づく自動	ネイティブバージョンを介した自動 defaultChannel + 多数の戦略
シーケンスバージョン	基本的なサポート	高度な__CAPGO_KEEP_0__ --disable-auto-update (メジャー/マイナー/パッチ)
ネイティブバージョン制約	アプリフロー ダッシュボードでの手動設定	組み込み --min-update-version / --auto-min-update-version メタデータ チャンネルとともに
チャンネル管理	Web UI + CLI	Web UI + CLI + API
Web UI + __CAPGO_KEEP_0__ + __CAPGO_KEEP_1__	デバイス オーバーライド	Full control via Dashboard/API
フル コントロールを通じてダッシュボード/__CAPGO_KEEP_0__	ダウン グレード防止	はい、以下の方法で --no-downgrade
バージョン管理	手動のブランチ/チャンネル管理	チャンネル優先の自動管理
自主管理	いいえ	はい（完全な制御）
バージョン分析	基本	バージョンごとの詳細なメトリクス

AppFlowの平行性とその先

Capgoが提供する すべてのバージョン対象機能 AppFlowが提供した機能に加えて、追加の制御メカニズムが含まれています。 AppFlowの自動バージョンマッチングに依存していた場合は、Capgoでも安全で、より柔軟性があります。

トラブルシューティング

更新を受け取らないユーザー

確認してください:

1. チャンネル割り当て: デバイスが正しいチャンネルにありますか?

   const channel = await CapacitorUpdater.getChannel()
   console.log('Current channel:', channel)

2. バージョン制約: バンドルのネイティブバージョン要件があるかどうかを確認してください。

   • ダッシュボード → バンドル → 「ネイティブバージョン」列を確認してください。

3. Semver設定: チャネルの disable-auto-update 設定

   npx @capgo/cli channel list

4. デバイスオーバーライド: デバイスが手動オーバーライドしているかどうかを確認してください。

   • ダッシュボード → デバイス → デバイスを検索 → チャネル/バージョンを確認してください。

バンドルが間違ったバージョンに配信された

1. デフォルトチャンネルを確認: 正しいチャンネルが選択されていることを確認する capacitor.config.ts
2. バンドルアップロードを確認: 対応するチャンネルにバンドルがアップロードされたことを確認する
3. 最小バージョンアップデートを確認: 最小バージョンアップデートが設定されていて、チャンネルが --min-update-version (または --auto-min-update-version) を使用していることを確認する --disable-auto-update metadata

古いバージョンに影響を与える変更

1. 直ちの修正: 影響を受けるデバイスに安全なバンドルを強制適用する
   • ダッシュボード → デバイス → 一括選択 → バージョン設定
2. 長期対策: バージョン化されたチャネルを作成し、分離されたブランチを維持する
3. 予防: 更新をロールアウトする前に、代表的なデバイスで更新をテストする

Ionic AppFlow からマイグレーション

Ionic AppFlow からマイグレーションする場合 , バージョン対象は __CAPGO_KEEP_0__ における、改善された柔軟性とともに、非常に類似しています:, version targeting works very similarly in Capgo, with improved flexibility:

セクション「概念マッピング」

AppFlow Concept	Capgo Equivalent	Notes
Deploy Channel	Capgo Channel	同様の概念、より強力なもの
ネイティブバージョンロック	--min-update-version / --auto-min-update-version	より細かい制御
チャンネル優先順位	優先順位の順序 (override → クラウド → デフォルト)	より透明な優先順位
展開対象	チャンネル + semver制御	利用可能な複数の戦略
生産チャンネル	production チャンネル (または任意の名前)	柔軟な名前付け
Gitベースのデプロイ	CLI ブランチからバンドルアップロード	同じワークフロー
自動バージョンマッチング	defaultChannel + バージョン制約	複数の戦略を組み込んだ強化

AppFlowユーザーのための主な違い

1. より多くの制御: Capgoが提供する複数の戦略（チャネル、semver、ネイティブバージョン）を組み合わせることができます
2. よりよい可視性: ダッシュボードでバージョン分布と互換性の問題を表示
3. APIアクセス: バージョン対象の制御にプログラムを使用
4. 自社ホスティング: 同じバージョンロジックでアップデートサーバーを実行するオプション

移行手順

1. AppFlowチャンネルをマップする CapgoのCapgoチャンネル（通常1:1）
2. 設定 defaultChannel に capacitor.config.ts 各主なバージョン
3. semverルールを設定 バージョン境界での自動ブロッキングが必要な場合
4. バージョン固有のバンドルをアップロード 使用 --min-update-version （チャンネルはメタデータ戦略を使用している必要があります）
5. バージョン分布を監視 CapgoのCapgoダッシュボード

完全な移行ガイド

完全な移行のための指示を含むSDKの置き換えとAPIのマッピングについては、 AppFlowからCapgoへの移行ガイド.

高度なパターン

バージョンごとの段階的なロールアウト

// Gradually migrate v1 users to v2
async function migrateUsers() {
  const deviceId = await CapacitorUpdater.getDeviceId()
  const rolloutPercentage = 10 // Start with 10%

  // Hash device ID to get deterministic percentage
  const hash = hashCode(deviceId) % 100

  if (hash < rolloutPercentage) {
    // User is in rollout group - migrate to v2
    await CapacitorUpdater.setChannel({ channel: 'v2' })
  }
}

バージョンごとの機能フラグ

// Enable features based on native version
async function checkFeatureAvailability() {
  const info = await CapacitorUpdater.getDeviceId()
  const nativeVersion = info.nativeVersion

  if (compareVersions(nativeVersion, '2.0.0') >= 0) {
    // Enable features requiring v2.0.0+
    enableNewCameraFeature()
  }
}

バージョン間のA/Bテスト

// Run A/B tests within same native version
async function assignABTest() {
  const nativeVersion = await getNativeVersion()

  if (nativeVersion.startsWith('2.')) {
    // Only A/B test on v2 users
    const variant = Math.random() < 0.5 ? 'v2-test-a' : 'v2-test-b'
    await CapacitorUpdater.setChannel({ channel: variant })
  }
}

概要

Capgoはバージョンに特化したアップデートの配信に複数の戦略を提供します。

1. チャンネルベースのルーティング: バージョンを自動的に分離する defaultChannel
2. シーケンスバージョニング: メジャー/マイナー/パッチ境界を超えてアップデートを防止する
3. ネイティブバージョン制約: バンドルのための最低限のネイティブバージョンを要求する
4. 自動ダウングレード防止: __CAPGO_KEEP_0__
5. :: Manual control for testing and targeting

:

For more details on specific features:

• : :
• : :
• : :

:

バージョン ターゲティングを使用している場合 バージョン ターゲティング バージョン ターゲティングを使用してチャンネル ルーティングとステージド ロールアウトを計画するには、それを チャンネル チャンネル チャンネル チャンネル ベータ テスト ソリューション ベータ テスト ソリューションにおける製品ワークフロー Beta Testing Solution for the product workflow in Beta Testing Solution, and バージョン対象化ソリューション バージョン対象化ソリューション向け製品ワークフロー