バージョン対象

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

Ionic AppFlowから移行する場合

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

概要

Capgo’s version targeting system allows you to:

• __CAPGO_KEEP_0__のバージョン対象システムは、次の機能を提供します: ユーザーに、nativeアプリのバージョンに基づいて更新を提供します。
• 破壊的な変更を防ぎます。 非互換のアプリのバージョンに到達するのを防ぎます。
• 複雑なロジックなしで複数のアプリのバージョンを管理します。 同時に更新を実行します。
• 特定のユーザー セグメントに更新を提供します。 バージョン ターゲットの重要性 (特にAppFlowユーザー向けに)

バージョン ターゲットの重要性 (特にAppFlowユーザー向けに) のセクション

AppFlow は、自動的にライブ更新のバンドルを native アプリのバージョンにマッチさせ、古い native __CAPGO_KEEP_0__ に向けて不互換の JavaScript を配信するのを防ぎました。 AppFlow, 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_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

この 推奨アプローチ メジャーバージョンアップデートと破壊的変更の管理に適したアプローチです。AppFlowの配信モデルに似ています。

例

• (100,000ユーザー) → バージョンマッチングフローの例 production チャンネル
• App v2.x (50,000 users with breaking changes) → v2 チャンネル
• App v3.x (10,000 beta users) → v3 チャンネル

実装

Step 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 チャンネルルーティングは自動的に行われます。
• 明確な区別 各バージョンには独自のアップデートパイプラインがあります。
• 柔軟なターゲット 特定のバージョングループにアップデートをプッシュできます。
• 安全なロールアウト 互換性のないバージョンには破壊的な変更が届きません。

戦略 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
• ユーザーは 受け取らない バージョン 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：ネイティブバージョン制約」

この戦略は、チャンネルmin_update_version) on each bundle so Capgo only delivers it to devices whose native binary is new enough.

戦略（）を使用します。 この戦略を使用します。 この戦略を使用します。--disable-auto-update metadataStrategy 3: Native Version Constraints --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

Capgo Builderのしくみ

メタデータ戦略により、バンドルのネイティブベースラインより下のデバイスはアップデートをスキップします。バンドルのバージョン以上のデバイスのみがアップデートを受け取ります。詳しくはversion_build互換性 min_update_version を参照してください。 Capgoの利用例 Capgoの利用例 --auto-min-update-version Capgoの利用例

Capgoの利用例

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 Capgo ダッシュボードで

1. Go to チャンネル コンテキスト: Capgo リリース チャネル機能名。ページ/エリア: Capgo ソリューション マーケティング ページ。ロール: 短い UI ラベルまたはナビゲーション アイテム。ページ: solutions/white-label.astro。メッセージ キー `solutions_white_label_visual_cell2_value` (ソリューション ホワイト ラベル ビジュアル セル2 値)。
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. クリック Channelを設定 または Channelを設定するか、バンドルバージョンを指定して上書き
3. 上書きしたソースからデバイスが更新を受信します
4. テストアップデート

デバイス上でユーザー全員に配布する前に、自分のデバイスでアップデートをテストするには、デバイス上でオーバーライドを使用してください。

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

「完全な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 in capacitor.config.ts
4. デフォルトチャンネル (Cloudflare設定) - 最低優先度

優先度の例

ユーザーのアプリが defaultChannel: 'v2' ですが、ユーザーのデバイスを 'beta' ダッシュボードで設定すると、ユーザーは 'beta' チャンネルからアップデートを受け取ることになります。

デバイスのオーバーライドUIは、ダッシュボードまたはPublic APIからのみオーバーライドを表示します。デバイス上で setChannel() アプリから呼び出すと、チャンネルをバックエンドと検証し、ローカルに保存します。

ベストプラクティス

1. メジャーバージョンでは常にdefaultChannelを設定する

// ✅ 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 自動
バージョン	セマンティック バージョニング	基本的なサポート --disable-auto-update 高度なサポート
ネイティブ版のバージョン制約	アプリフロー ダッシュボードでの手動設定	組み込み --min-update-version / --auto-min-update-version メタデータ チャンネルとともに
チャンネル管理	Web UI + CLI	Web UI + CLI + API
デバイスのオーバーライド	デバイスごとの制限されたコントロール	フルコントロールはダッシュボードの API から
ダウングレードの自動防止	はい	はい、以下の方法で --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. 直ちの修正: 影響を受けるデバイスに安全なバンドルを強制適用する
   • ダッシュボード → デバイス → Bulk select → バージョン設定
2. 長期的な修正: バージョン化されたチャンネルを作成し、分離されたブランチを維持
3. 予防: 更新をロールアウトする前に、代表的なデバイスでテスト

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

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

Ionic AppFlow からマイグレーションする場合、バージョン対象は __CAPGO_KEEP_0__ における、改善された柔軟性とともに、非常に似たように機能します。

AppFlow Concept	Capgo Equivalent	Notes
Deploy Channel	Capgo Channel	Native Version Lock
より細かい制御	--min-update-version / --auto-min-update-version	Channel Priority
チャンネル優先順位 (override → cloud → default)	より透明な優先順位	デプロイ対象
Deploy Channel	チャンネル + 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のマッピングについては、以下の CapgoへのAppFlowの移行ガイド.

高度なパターン

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

// 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. 自動ダウングレード防止: 最新バージョンのネイティブに古いバンドルを配信しない
5. Device Overrides: テストとターゲットのための手動コントロール

これらの戦略を組み合わせることで、より多くの柔軟性とコントロールを持つAppFlowスタイルの自動更新配信が可能になります。アプリのバージョニングとデプロイワークフローに最も適したアプローチを選択してください。

特定の機能についての詳細はこちら

• Breaking Changes Guide - 詳細なチャンネルバージョニング戦略
• Channel Management - チャンネル構成の完全なリファレンス
• Update Behavior - ネイティブのバージョン遅延と条件

Version Targetingから続きます

あなたが使用している バージョン ターゲティング バージョン ターゲティング バージョン ターゲティング チャンネル チャンネル チャンネル チャンネル ベータテスト ソリューション ベータテスト ソリューション product workflow in Beta Testing Solution, and バージョン対象化ソリューション バージョン対象化ソリューション用の製品ワークフロー