バージョンターゲティング

このガイドでは、ユーザーのネイティブアプリのバージョンに基づいて、互換性のある最新の bundle を自動的に配信する方法を説明します。 Ionic AppFlow のアプローチと同様です。これにより、アップデート管理が簡素化され、ロールアウトが迅速化され、互換性の問題も防げます。

Ionic AppFlow からの移行をご検討中ですか？

Ionic AppFlowをご利用中の方は、このガイドが特に重要です。AppFlowはアップデートとネイティブバージョンを自動的に紐付けていましたが、Capgoでも同様の機能に加え、より高度な制御と柔軟性を提供します。詳細は AppFlow移行ガイド のステップバイステップの移行手順をご覧ください。

概要

Capgoのバージョンターゲティング機能により、以下が可能になります：

• 互換性のあるアップデートの自動配信 ユーザーのネイティブアプリのバージョンに基づいた配信
• 破壊的変更の防止 互換性のないアプリバージョンへの配信を回避
• 複数のアプリバージョンの管理 複雑なロジックなしで同時に管理
• アップデートをシームレスに配信 特定のユーザーセグメントへ

バージョンターゲティングが重要な理由（特にAppFlowユーザーにとって）

もしあなたが Ionic AppFlowに馴染みがあれば、ユーザーに互換性のあるアップデートのみを確実に届けることがいかに重要か、ご存じでしょう。AppFlowは live update bundle をネイティブアプリのバージョンに自動でマッチさせ、古いネイティブ code に互換性のないJavaScriptが配信されるのを防いでいました。

Capgo は同じ安全性を保証しますが、さらに以下の機能も備えています：

• バージョンマッチングをより細かく制御
• 複数の戦略（チャネル、semver、ネイティブ制約）
• バージョン配信状況の可視性向上
• API と CLI は、ダッシュボード管理と併せて制御されます

この手法は、特に以下のような場合に有効です：

• アプリのメジャーバージョンが複数に分かれている場合（例：v1.x, v2.x, v3.x）
• 破壊的変更を導入しつつ、後方互換性を維持する必要がある場合
• 新しいbundle が古い Native code を壊すのを防ぎたい場合
• ユーザーをあるバージョンから別のバージョンへ段階的に移行させる場合
• AppFlow からの移行を行っている場合 かつ、これまでと同様のアップデートの安全性を維持したい場合

仕組み

Capgo は、ユーザーに互換性のあるアップデートを配信するために多層的なアプローチを採用しています：

1. Native バージョン制約: 非互換な Native Build バージョンへの bundle 送信を防止します
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のデリバリーモデルに似ています。

シナリオ例

• アプリ v1.x (ユーザー数 100,000人) → production チャンネル
• アプリ v2.x (破壊的変更を含むユーザー数 50,000人) → v2 チャンネル
• アプリ v3.x (ベータユーザー 10,000人) → v3 チャンネル

実装方法

ステップ 1: メジャーバージョンごとに Channel を設定する

// 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: Channel を作成する

# Create channels for each major version
npx @capgo/cli channel add production
npx @capgo/cli channel add v2
npx @capgo/cli channel add 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: バージョン固有の Bundle をアップロード

# 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

自動ルーティング

ユーザーがアプリを開くと、インストールされているアプリ Bundle 内の defaultChannel に基づき、指定された channel に自動的に接続されます。JavaScript の code を変更する必要はありません！

メリット

• code の変更は不要 - チャネルルーティングは自動で行われます
• 明確な分離 - 各バージョンに独自のアップデートパイプラインがあります
• 柔軟なターゲティング - 特定のバージョングループにアップデートを配信
• 安全なロールアウト - 破壊的変更が互換性のないバージョンに届くことはありません

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

Capgo の組み込みの セマンティックバージョニング制御を 使用して、バージョン境界を越えたアップデートを防ぎます。

メジャーバージョン間での自動アップデートを無効化

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

この設定の意味：

• アプリバージョン 1.2.3 のユーザーは、次までのアップデートを受け取ります： 1.9.9
• ユーザーは 決して バージョン 2.0.0 を自動的には受け取りません
• 古いネイティブ code に破壊的変更が及ぶのを防ぎます
• 比較には、送信された以下の Native baseline が使用されます： 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) アプリのバージョンに対して適用されます。バージョン番号が以下に従っていることを確認してください： MAJOR.MINOR.PATCH である必要があります。

戦略 3: Native Version Constraints

各bundleに最小ネイティブアプリバージョン（min_update_version) を指定することで、Capgo はネイティブバイナリが要件を満たすデバイスにのみ配信されます。

これは、 metadata 戦略（--disable-auto-update metadata) と、 --min-update-version または --auto-min-update-version アップロード時に。 --native-version CLI フラグ。

チャンネルでmetadata targetingを有効にする

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

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

bundleをアップロードする際、そのbundleを受け取れる最小のネイティブバージョンを指定します：

# 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: 自動ダウングレードの防止

ユーザーが現在の Native Build バージョンよりも古い bundle を受信するのを防ぎます。

Channel Settings で有効にする

Capgo ダッシュボードにて:

1. 以下に移動します： チャンネル → チャネルを選択
2. 有効にする “Native での自動ダウングレードを無効にする”
3. 変更を保存

または CLI 経由:

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

例

• ユーザーのデバイス: Native バージョン 1.2.5
• チャネル bundle: バージョン 1.2.3
• 実績: アップデートがブロックされました（ダウングレードになるため）

以下のようなケースで有効です：

• ユーザーがApp Storeから手動で新しいバージョンをインストールした場合
• 常に最新のセキュリティパッチをユーザーに適用させたい場合
• デグレ（先祖返り）によるバグを防ぎたい場合

戦略 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. クリック Channel を設定 または Version を設定
3. 特定の channel または bundle version で上書き
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のユーザー数比較
• バージョンごとのBundle採用率
• バージョンごとのエラー・クラッシュ発生数

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)

チャネルの優先順位

複数のChannel設定が存在する場合、Capgo は以下の優先順位に従います：

1. デバイスオーバーライド (Dashboard または API) - 最優先。Device Override UI に表示されます
2. ローカルのプラグインチャンネル 経由で setChannel() - デバイス内にのみ保存され、Device Override UI には表示されません
3. defaultChannel capacitor.config.ts 内
4. デフォルトチャンネル (Cloud 設定) - 最低優先度

優先順位の例

ユーザーのアプリが以下の場合 defaultChannel: 'v2' ただし、デバイスを以下にオーバーライドした場合 'beta' ダッシュボード上で、channelから 'beta' アップデートを受け取ります。

Device Override UIには、ダッシュボードまたはPublic APIから設定されたオーバーライドのみが表示されます。アプリから setChannel() 呼び出すと、バックエンドでchannelが検証され、その後デバイスにローカル保存されます。

ベストプラクティス

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. バージョンごとの配信状況を監視

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

• ユーザーは新しい Native Build へ移行していますか？
• 古いバージョンに依然として高いトラフィックがありますか？
• 古いチャンネルを廃止すべきでしょうか？

Ionic AppFlowとの比較

以下の環境から移行するチーム向け： Ionic AppFlow、Capgo のバージョン・ターゲティングとの比較は以下の通りです：

機能	Ionic AppFlow	Capgo
バージョンベースのルーティング	ネイティブバージョンに基づき自動設定	〜経由で自動設定 defaultChannel + 複数の戦略
セマンティックバージョニング	基本サポート	〜による高度な設定 --disable-auto-update (メジャー/マイナー/パッチ)
ネイティブバージョンの制約	AppFlowダッシュボードでの手動設定	組み込み済み --min-update-version / --auto-min-update-version メタデータチャネル付き
チャネル管理	Web UI + CLI	Web UI + CLI + API
デバイスオーバーライド	デバイス単位の制御は限定的	Dashboard/API でフルコントロール
自動ダウングレード防止	はい	はい（経由） --no-downgrade
複数バージョンのメンテナンス	手動でのブランチ/チャネル管理	チャネル優先度による自動化
セルフホスティング	いいえ	はい（完全な制御が可能）
バージョン分析	基本	バージョンごとの詳細なメトリクス

AppFlowと同等の機能、さらにその先へ

Capgo は、 AppFlowが提供していたすべてのバージョンターゲティング機能を 備えているだけでなく、追加の制御メカニズムも提供します。AppFlowの自動バージョンマッチングを利用していた場合でも、Capgo ならば、より高い柔軟性を持ちつつ、同様の安全性で利用できます。

トラブルシューティング

ユーザーにアップデートが届かない

以下の項目を確認してください：

1. チャンネルの割り当て: デバイスが正しいチャンネルに設定されているか確認

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

2. バージョンの制約: bundle に Native Build のバージョン要件が含まれているか確認

   • Dashboard → Bundles → “Native Version” 列を確認

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

   npx @capgo/cli channel list

4. デバイスオーバーライド: デバイスに手動オーバーライドが設定されているか確認

   • Dashboard → Devices → デバイスを検索 → channel/versionを確認

Bundleが誤ったバージョンに配信される

1. defaultChannelを確認: 正しいchannelが指定されているか確認 capacitor.config.ts
2. Bundleのアップロードを確認: bundleが意図したchannelにアップロードされたか確認
3. min update versionを確認: 確認 --min-update-version (または --auto-min-update-version) が設定されており、そのチャンネルは使用しています --disable-auto-update metadata

破壊的変更が旧バージョンに影響する

1. 即時対応: 対象デバイスを安全なbundleに上書きする
   • Dashboard → Devices → 一括選択 → Set Version
2. 恒久的な対策: バージョンごとのチャンネルを作成し、ブランチを分けて管理する
3. 予防: リリース前に、必ず代表的なデバイスでアップデートのテストを行う

Ionic AppFlowからの移行

もし以下から移行する場合、 Ionic AppFlow、Capgo のバージョンターゲティングも非常に似た仕組みですが、より柔軟性が向上しています：

コンセプトの対応表

AppFlowのコンセプト	Capgo での相当する機能	備考
デプロイ先チャンネル	Capgo チャンネル	コンセプトは同じ、より強力に
Native Version Lock	--min-update-version / --auto-min-update-version	より細かな制御が可能に
チャンネルの優先度	Channelの優先順位 (override → cloud → default)	より明確な優先順位
デプロイ先ターゲット	Channel + semver による制御	複数の戦略を利用可能
本番チャンネル	production channel (または任意の名前)	柔軟な命名
Gitベースのデプロイ	ブランチからのCLI bundle upload	同一のワークフロー
バージョンの自動マッチング	defaultChannel + バージョン制約	複数の戦略で機能を強化

AppFlowユーザー向けの主な違い

1. より高度なコントロール: Capgo では、組み合わせ可能な複数の戦略（channels、semver、native version）を利用できます
2. 優れた可視性: ダッシュボードでバージョンの分布や互換性の問題を把握できます
3. API へのアクセス: バージョン指定を完全にプログラム制御
4. セルフホスティング: 同様のバージョンロジックを持つ自社更新サーバーの運用オプション

移行手順

1. AppFlow のチャンネルを Capgo のチャンネルにマッピング（通常は 1:1）
2. 設定 defaultChannel における capacitor.config.ts メジャーバージョンごとに
3. semver ルールの設定 バージョン境界での自動ブロックを行いたい場合
4. バージョン固有のbundleをアップロードする を使用して --min-update-version (channelはmetadata戦略を使用する必要があります)
5. バージョンの配信状況をモニタリングする 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' })
  }
}

バージョン別のFeature Flag

// 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. チャンネルベースのルーティング: Automatic version separation via defaultChannel
2. セマンティックバージョニング: メジャー/マイナー/パッチ境界を越えたアップデートを防止
3. ネイティブバージョンの制約: バンドルに最小ネイティブバージョンを要求
4. 自動ダウングレードの防止: 新しいネイティブバージョンに古いバンドルを配信しない
5. デバイスの上書き設定: テストやターゲット指定のための手動制御

これらの戦略を組み合わせることで、AppFlowのような自動アップデート配信を、より高い柔軟性とコントロール性で実現できます。アプリのバージョニングやデプロイワークフローに最適なアプローチを選択してください。

各機能の詳細についてはこちら:

• 破壊的変更ガイド - チャネルのバージョン管理戦略の詳細
• チャネル管理 - チャネル設定の完全リファレンス
• アップデートの動作 - Native Buildのバージョン遅延と条件

Version Targetingの次のステップ

使用している場合 バージョンターゲティング チャンネルルーティングと段階的ロールアウトを計画するには、次と組み合わせてください： チャンネル Channelsの実装の詳細については、 チャンネル Channelsの実装の詳細については、 チャンネル Channelsの実装の詳細については、 ベータテストソリューション ベータテストソリューションのプロダクトワークフロー向け、および バージョンターゲティングソリューション バージョンターゲティングソリューションのプロダクトワークフロー向け。