バージョン目標

このガイドでは、ユーザーのネイティブアプリバージョンに基づいて最新の互換性のあるバンドルを自動的にユーザーに提供する方法を説明します。 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:

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

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

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

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

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

JavaScript の変更が必要ありません!

• 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
• __CAPGO_KEEP_0__を使用するnative基準が送信されます 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：ネイティブバージョン制約

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

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

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

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

「How It Works」

ネイティブバージョン 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. 「__CAPGO_KEEP_0__」にアクセス チャンネル → チャンネルを選択
2. 有効 「ネイティブ下で自動ダウングレードを無効にする」
3. 変更を保存

または、CLIを使用して:

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

例

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

これは、以下のシナリオで役立ちます。

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

デバイスレベルターゲット

__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' })
  }
}

コピー

In the Capgo dashboard:

1. __CAPGO_KEEP_0__のダッシュボードで Go to デバイス
2. → デバイスを検索 Click、チャネルを設定 または バージョンを設定
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. __CAPGO_KEEP_0__.config.ts in capacitor.config.ts
4. (Cloud設定) - 最低優先度 Default Channel

優先順位の例

ユーザーのアプリが defaultChannel: 'v2' ですが、ユーザーのデバイスを 'beta' ダッシュボードで設定した場合、ユーザーは 'beta' チャンネル。

デバイスのオーバーライドUIは、ダッシュボードまたはPublic APIからのみオーバーライドを表示します。 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__のバージョン対象設定の比較 Capgo, 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
デバイスオーバーライド	デバイスレベル制御の制限	Dashboard/API によるフルコントロール
ダウングレード防止	Yes	Yes via __CAPGO_KEEP_0__ --disable-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. Check Bundle Upload: 対応したチャネルにバンドルが正常にアップロードされたことを確認する
3. Inspect Native Version: 正しいフラグが使用されたことを確認する --native-version Breaking Changes Affecting Old Versions

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

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

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

イオニクン アプリフローから移行している場合 イオニクン アプリフロー, バージョン ターゲットングは Capgo における柔軟性の向上とともに、非常に類似しています:

概念マッピング

アプリフロー コンセプト	Capgo の同等	Notes
展開チャネル	Capgo チャネル	より強力な概念
ネイティブ バージョン ロック	--native-version フラグ	より細かい制御
チャネル優先度	チャネル優先度 (override → クラウド → デフォルト)	より透明な優先度
展開対象	チャネル + 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 ダッシュボード

マイグレーションガイド

For complete migration instructions including SDK replacement and API mapping, see the AppFlow to Capgo Migration Guide.

高度なパターン

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

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

テストとターゲット設定のための手動制御

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

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

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

Capgoを使用している場合 __CAPGO_KEEP_0__ チャンネルルーティングとステージドロールアウトの計画に使用するため、__CAPGO_KEEP_0__に接続してください。 __CAPGO_KEEP_0__ __CAPGO_KEEP_0__の実装詳細については、__CAPGO_KEEP_0__を参照してください。 __CAPGO_KEEP_0__ __CAPGO_KEEP_0__の実装詳細については、__CAPGO_KEEP_0__を参照してください。 __CAPGO_KEEP_0__ __CAPGO_KEEP_0__の実装詳細については、__CAPGO_KEEP_0__を参照してください。 ベータテストソリューション ベータテストソリューションで使用する製品ワークフローについては、ベータテストソリューションを参照してください。 バージョン目標ソリューション 製品ワークフローについてのバージョン対象解決策。