バージョン目標

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

Ionic AppFlowから移行する場合

If you’re coming from Ionic AppFlow, this guide is especially important for you. AppFlow automatically matched updates to native versions, and Capgo provides the same capability with even more control and flexibility. See the AppFlowの移行ガイド Overview

「概要」のセクション

Capgo’s version targeting system allows you to:

• ユーザーに提供する ユーザーのネイティブアプリバージョンに基づいて
• 破壊的な変更 互換性のないアプリバージョンに到達するのを防ぐ
• 複雑なロジックなしで 複数のアプリバージョンを管理する
• 順調に更新を展開 特定のユーザー セグメントに

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

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

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

• 複数の戦略 (チャネル、semver、ネイティブ制約)
• バージョン配布の視覚化
• __CAPGO_KEEP_0__
• 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

このアプローチは、バージョンアップやメジャーバージョンアップを管理するための推奨方法です。AppFlowの配信モデルと似ています。 推奨アプローチ バージョンアップやメジャーバージョンアップを管理するためのアプローチ

例

• App v1.x (100,000ユーザー) → production チャネル
• App v2.x (50,000ユーザーにバージョンアップが含まれる) → v2 チャネル
• 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

自動ルーティング

ユーザーがアプリを開くと、インストール済みのアプリパッケージに基づいて自動的に指定されたチャネルに接続します。JavaScript の __CAPGO_KEEP_0__ の変更は必要ありません! defaultChannel in their installed app bundle. No JavaScript code changes required!

「利点」セクション

• Zero code changes - チャネルルーティングは自動で行われます
• 保護された分離 - 各バージョンには独自のアップデートパイプラインがあります
• 柔軟なターゲット設定 - 特定のバージョングループにアップデートをプッシュする
• 安全なロールアウト - 不相応バージョンに到達することなく、破壊的な変更は行われません

Strategy 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 バージョン
• Prevents breaking changes from reaching older native 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) に従う場合にのみ機能します。 アプリのバージョンに semver を使用してください。バージョン番号が指定された形式に従っていることを確認してください。 戦略 3: ネイティブ バージョン制約 MAJOR.MINOR.PATCH セマンティック バージョニング (semver) に従う必要があります。

バージョン番号が指定された形式に従っていることを確認してください。

バンドルに最小限のネイティブ バージョン要件を指定して、互換性のないデバイスへの配信を防止します。

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

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

# 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_KEEP_0__設定で有効にする

Capgoダッシュボードで:

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

またはCLIから:

npx @capgo/cli channel set production --disable-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. デバイス → デバイスを検索 クリック
2. チャネルを設定 In the __CAPGO_KEEP_0__ dashboard: または __CAPGO_KEEP_0__
3. __CAPGO_KEEP_0__の特定のチャネルまたはバンドルバージョンで上書き
4. デバイスは上書きされたソースからアップデートを受け取る

テストアップデート

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

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

ここでは、すべての戦略を組み合わせた完全な例が示されています。

1. 初期設定 (App 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設定) - 最低優先度

Precedence Example

If a user’s app has defaultChannel: 'v2' but you override their device to 'beta' in the dashboard, they’ll receive updates from the 'beta' channel.

The Device Override UI only lists overrides set from the dashboard or Public API. Calling setChannel() from the app validates the channel with the backend, then stores it locally on the device.

Best Practices

1. Always Set defaultChannel for Major Versions

// ✅ 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:

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

AppFlowの平行性とそれ以上

Capgoが提供する すべてのバージョン対象機能 AppFlowが提供した機能に加えて、追加の制御機構が含まれます。 AppFlowの自動バージョンマッチングに依存していた場合、Capgoはより多くの柔軟性と安全性を提供します。

トラブルシューティング

ユーザーが更新を受け取っていない

確認してください

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

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

2. バージョン制約: バンドルにネイティブのバージョン要件が含まれていますか

   • DASHBOARD → バンドル → 「ネイティブ バージョン」列を確認

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

   npx @capgo/cli channel list

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

   • DASHBOARD → デバイス → デバイスを検索 → チャンネル/バージョンを確認

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

1. デフォルトのチャンネルを確認: 正しいチャネルが選択されていることを確認する capacitor.config.ts
2. Check Bundle Upload: 指定されたチャネルにバンドルが正常にアップロードされたことを確認する
3. Inspect Native Version: 確認 --native-version flag が正しく使用されたことを確認する

Breaking Changes Affecting Old Versions

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

Ionic AppFlow からの移行

Ionic AppFlow から移行している場合 Ionic AppFlowバージョン対象の機能は、Capgo で大幅に改善された柔軟性とともに、非常に類似しています

概念マッピング

__CAPGO_KEEP_0__ の同等	Capgo Equivalent	Notes
Deploy Channel	Capgo Channel	同様の概念、より強力なもの
Native Version Lock	--native-version フラグ	より細かい制御
Channel Priority	Channel precedence (override → cloud → default)	より透明な順位付け
Deployment Target	Channel + semver制御	複数の戦略が利用可能
本番チャネル	production チャネル (または任意の名前)	柔軟な名前付け
Gitベースのデプロイ	CLI ブランチからバンドルアップロード	同じワークフロー
自動バージョンマッチング	defaultChannel + バージョン制約	複数の戦略を含む強化

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

1. より多くの制御: Capgo があなたに複数の戦略 (チャネル、semver、ネイティブ バージョン) を提供します。これらの戦略を組み合わせることができます。
2. より良い視野: ダッシュボードはバージョン分布と互換性の問題を表示します。
3. API アクセス: プログラム上でバージョンをターゲットにするための完全な制御
4. 自社ホスティング: 同じバージョンロジックを持つアップデートサーバーを実行するためのオプション

移行ステップ

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

マイグレーションガイド

完全な移行手順、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. デバイスオーバーライド: マニュアルコントロールによるテストとターゲット

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

詳細な特徴については:

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

バージョン目標から続けて

Capgoを使用している場合 バージョン対象設定 チャンネルルーティングと段階的なロールアウトを計画するには、 チャンネル チャンネル チャンネル チャンネル ベータテストソリューション 製品ワークフロー バージョン対象設定ソリューション __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ __CAPGO_KEEP_0__