バージョン目標

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

Ionic AppFlowから移行する場合

Ionic AppFlowから来た方は、このガイドは特に重要です。 AppFlowは、自動的にネイティブバージョンとアップデートをマッチングし、Capgoはその機能をさらに制御し、柔軟性を提供します。 AppFlowの移行ガイド for step-by-step migration instructions.

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

Capgo’s version targeting system allows you to:

• 複雑なロジックなしで、複数のアプリバージョンを同時に管理する Overview
• セクションのタイトルは「Overview」です。 __CAPGO_KEEP_0__のバージョン対象システムは、次の機能を提供します。
• 自動的に互換性のあるアップデートを配信する ユーザーにネイティブアプリのバージョンに基づいて配信する
• 順滑にアップデートを展開 特定のユーザーセグメントに

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

あなたがIonic AppFlowのことをよく知っている場合 、ユーザーが互換性のあるアップデートを受け取ることを保証することは非常に重要です。 AppFlowは、ライブアップデートパッケージをネイティブアプリのバージョンと自動的にマッチさせ、互換性のないJavaScriptが古いネイティブ__CAPGO_KEEP_0__に配信されるのを防ぎました。codeは同じ安全性の保証を提供

Capgo provides the same safety guaranteesバージョンマッチングのより細かい制御

• 複数の戦略（チャンネル、semver、ネイティブ制約）
• バージョン配布のより良好な視覚化
• Why Version Targeting Matters (Especially for AppFlow Users)
• API と CLI はダッシュボード管理とともに制御します。

このアプローチは、特に以下のシナリオで便利です。

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

「How It Works」というセクション

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

1. Native Version Constraints: 不適切なネイティブバージョンに配布されるバンドルを防止する
2. Channel-Based Routing: 異なるアプリバージョンを異なるアップデートチャンネルにルーティングする
3. Semantic Versioning Controls: メジャー/マイナー/パッチ境界を超えたアップデートを自動的にブロックする
4. Device-Level Overrides: 特定のデバイスまたはユーザーグループをターゲットする

Version Matching Flow

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]

Strategy 1: Channel-Based Version Routing

This is the recommended approach for managing breaking changes and major version updates. It’s similar to AppFlow’s delivery model.

Example Scenario

• App v1.x (100,000 users) → production channel
• App v2.x (50,000 users with breaking changes) → v2 channel
• App v3.x (10,000 beta users) → 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 - チャネルルーティングは自動で行われます
• Clear separation - 各バージョンには独自のアップデートパイプラインがあります
• Flexible targeting - 特定のバージョングループにアップデートをプッシュする
• Safe rollouts - 不相容バージョンに破壊的な変更は届きません

Strategy 2: Semantic Versioning Controls

Use Capgo’s built-in semantic versioning controls を使用して、バージョン境界を超えるアップデートを防止します。

メジャーバージョン間で自動更新を無効化

# 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 自動的に
• Prevents breaking changes from reaching older native code
• The comparison uses the native baseline sent as 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 を使用する必要があります。アプリのバージョン番号は

フォーマットでなければなりません。

バンドルに不適切なデバイスへの配信を防止するために、最小のネイティブバージョン要件を指定してください。

ネイティブバージョン遅延条件を使用

アップロードするバンドルに最小のネイティブバージョンを指定できます。

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

機能の仕組み

ネイティブバージョン 1.x のデバイスは、このバンドルを受信しないこと。2.0.0 以降のデバイスのみが受信します。この更新には、新しいネイティブ API またはプラグインが必要な場合に、完全に適しています。

使用例

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

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli bundle upload --native-version "2.0.0"

2. ネイティブ API の変更

   # Bundle uses new Capacitor 6 APIs
   npx @capgo/cli bundle upload --native-version "3.0.0"

3. 段階的な移行

   # Test bundle only on latest native version
   npx @capgo/cli bundle upload \
     --channel beta \
     --native-version "2.5.0"

Auto-Downgrade の防止

この機能では、ユーザーが現在のネイティブ バージョンよりも古いバンドルを受け取るのを防ぎます。

チャンネル設定で有効にする

Capgo ダッシュボードで:

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

または、CLI:

npx @capgo/cli channel set production --disable-downgrade

例

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

これは有用です:

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

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

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

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

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. 移動 デバイス → デバイスを検索
2. クリック チャンネルを設定 または バージョンを設定
3. 特定のチャネルまたはバンドルバージョンで上書き
4. デバイスは上書きされたソースからアップデートを受け取る

アップデートのテスト

デバイス上でアップデートをテストするには、利用者全員に配布する前に、利用者ごとにアップデートを上書きしてください。

アプリフロー スタイルのワークフロー

すべての戦略を組み合わせた完全な例です。

1. 初期設定 (アプリ v1.0.0)

# Create production channel with semver controls
npx @capgo/cli channel create production \
  --disable-auto-update major \
  --disable-downgrade

capacitor.config.ts

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

2. アプリケーション v2.0.0 のリリース中断

# Create v2 channel for new version
npx @capgo/cli channel create v2 \
  --disable-auto-update major \
  --disable-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 bundle upload \
  --channel production \
  --native-version "1.0.0"

# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli bundle upload \
  --channel v2 \
  --native-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' チャンネルから更新を受け取る。

The Device Override UI only lists overrides set from the dashboard or Public API. Calling setChannel() デバイスのオーバーライドUIを呼び出すと、

アプリから呼び出して、チャンネルをバックエンドと検証し、次にデバイス上でローカルに保存します。

「ベストプラクティス」のセクション

// ✅ 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. ロールアウト前にテストする

# Test on beta channel first
npx @capgo/cli bundle upload --channel beta

# Monitor for issues, then promote to production
npx @capgo/cli bundle upload --channel production

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

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

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

Ionic AppFlow と比較

__CAPGO_KEEP_0__のバージョン対象の比較 Ionic AppFlow, here’s how Capgo’s version targeting compares:

機能	Ionic AppFlow	Capgo
バージョンに基づくルーティング	ネイティブバージョンに基づく自動	ネイティブバージョンを介した自動 defaultChannel +複数の戦略
シーケンスバージョン	基本的なサポート	高度な --disable-auto-update (メジャー/マイナー/パッチ)
ネイティブバージョン制約	AppFlow ダッシュボード内での手動設定	Built-in --native-version CLI のフラグ
チャネル管理	Web UI + CLI	Web UI + CLI + API
デバイスオーバーライド	デバイスレベルでの制限されたコントロール	ダッシュボード/API でのフルコントロール
ダウングレード防止	Yes	Yes via __CAPGO_KEEP_0__ --disable-downgrade
Multi-version管理	手動ブランチ/チャンネル管理	チャンネル優先順位で自動化
自主ホスティング	No	Yes (フルコントロール)
バージョン分析	基本	バージョンごとの詳細なメトリクス

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. Check Bundle Upload: 指定されたチャネルにバンドルが正常にアップロードされたことを確認する
3. Inspect Native Version: 正しいフラグが使用されたことを確認する --native-version Breaking Changes Affecting Old Versions

: 旧バージョンに影響を与える変更点

1. : 直ちに影響を受けるデバイスに安全なバンドルを適用するDashboard → Devices → Bulk select → Set Version
   • : 長期的な修正
2. : デバイスのバージョンを一括で変更する: バージョン管理チャンネルを作成し、分離されたブランチを維持する
3. 防止: 更新をロールアウトする前に、代表的なデバイスで常にテストする

イオニクス アプリフローからの移行

イオニクス アプリフローから移行する場合 イオニクス アプリフローバージョン ターゲットの機能は、Capgoで大幅に改善された柔軟性とともに、非常に似ています

概念マッピング

アプリフロー コンセプト	Capgoの同等	Notes
展開チャネル	Capgo チャネル	同じ概念、より強力なもの
ネイティブバージョンロック	--native-version フラグ	より詳細な制御
チャネル優先度	チャネル優先度 (override → cloud → default)	より透明な優先度
展開対象	チャネル + semver制御	複数の戦略が利用可能
生産チャネル	production チャネル（または任意の名前）	柔軟な命名
Gitベースのデプロイ	CLI ブランチからバンドルアップロード	同じワークフロー
自動バージョンマッチング	defaultChannel バージョン制約の拡張	複数の戦略を活用した強化

AppFlowユーザ用の主な違い

1. More Control: Capgo が複数の戦略 (チャネル、semver、ネイティブ バージョン) を組み合わせて提供します。
2. Better Visibility: ダッシュボードではバージョン分布と互換性の問題が表示されます。
3. API Access: プログラム上でバージョンをターゲットにするための完全な制御が可能です。
4. Self-Hosting: 同じバージョンロジックで自分のアップデートサーバーを実行するオプションが用意されています。

Migration Steps

1. アプリフロー チャネルのマッピング を Capgo チャネル (通常 1:1) にマッピングする
2. バージョン defaultChannel に設定 capacitor.config.ts 各メジャーバージョンごとに
3. semver ルールを設定 バージョン境界での自動ブロッキングが必要な場合は
4. バージョンごとのバンドルをアップロード 使用 --native-version フラグ
5. バージョン分布を__CAPGO_KEEP_0__ ダッシュボードで監視 in Capgo dashboard

マイグレーションガイド

SDKの完全な移行手順、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. ：ネイティブ バージョンが最低限必要なバンドルを要求する
5. Device Overrides:

Manual control for testing and targeting

と組み合わせることで、より多くの柔軟性と制御を備えたAppFlowスタイルの自動更新配信が実現できます。アプリのバージョニングとデプロイワークフローに最も適したアプローチを選択してください。

• 詳細については、以下の特定の機能を参照してください: Breaking Changes Guide
• - 詳細なチャネルバージョニング戦略 Channel Management
• - 完全なチャネル構成のリファレンス Update Behavior

- ネイティブバージョン遅延と条件

__CAPGO_KEEP_0__は使用中の場合 バージョン対象設定 __CAPGO_KEEP_0__を__CAPGO_KEEP_1__と接続して __CAPGO_KEEP_1__ __CAPGO_KEEP_1__の実装詳細については __CAPGO_KEEP_1__ __CAPGO_KEEP_1__の実装詳細については __CAPGO_KEEP_1__ __CAPGO_KEEP_1__の実装詳細については ベータテスト ソリューション __CAPGO_KEEP_0__の製品ワークフローについては バージョン対象設定 ソリューション __CAPGO_KEEP_0__