__CAPGO_KEEP_0__

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

Ionic AppFlowから移行する

Ionic AppFlowから来た場合は、このガイドは特に重要です。AppFlowは自動的に更新をネイティブバージョンとマッチさせていましたが、Capgoは、より多くの制御と柔軟性を提供します。 AppFlow移行ガイド 移行のステップバイステップの指示が記載されています。

概要

Capgo’s version targeting system allows you to:

• __CAPGO_KEEP_0__のバージョン対象化システムにより、以下のことが可能になります: 自動的に、ユーザーのネイティブアプリのバージョンに合わせた更新を提供
• ユーザーのネイティブアプリのバージョンに合わせた更新を自動的に提供 不相応のアプリバージョンに到達する破壊的な変更を防止
• 不相応のアプリバージョンに到達する破壊的な変更を防止する 複雑なロジックなしで、複数のアプリバージョンを管理
• 複数のアプリバージョンを管理する 特定のユーザーセグメントに更新をシームレスに展開

特定のユーザーセグメントに更新をシームレスに展開する

バージョン対象化の重要性（特にAppFlowユーザー向け） Ionic AppFlowユーザーが互換性のあるアップデートを受け取ることを保証することは、非常に重要です。AppFlowは、ライブアップデートバンドルをネイティブアプリのバージョンと自動的にマッチさせ、互換性のないJavaScriptが古いネイティブcodeに配信されるのを防ぎます。

Capgoは同じ安全性の保証を提供します追加の機能もあります:

• バージョンマッチングのより細かい制御
• 複数の戦略（チャネル、semver、ネイティブ制約）
• バージョン配布の視覚化
• APIとCLIの制御はダッシュボード管理とともに

このアプローチは、特に以下のシナリオで役立ちます:

• ユーザーがアプリの異なるメジャーバージョン（例：v1.x、v2.x、v3.x）にいる場合
• 破壊的な変更をロールアウトする際に、後方互換性を維持する必要がある場合
• 新しいバンドルが古いネイティブcodeを破壊しないようにしたい場合
• You’re migrating users gradually from one version to another
• You’re migrating from AppFlow と同じ更新の安全性を維持したままユーザーを一つずつ別のバージョンに移行する

How It Works

Capgoは、互換性のある更新とマッチするために、複数層のアプローチを使用します:

1. Native Version Constraints: 不適合のネイティブバージョンに配布されるバンドルを防止する
2. Channel-Based Routing: 異なるアプリバージョンを異なる更新チャネルにルーティングする
3. Semantic Versioning Controls: メジャー/マイナー/パッチ境界を超えた更新を自動的にブロックする
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]

チャネルベースのバージョンルーティング

これは 推奨されるアプローチ メジャーバージョンアップデートや破壊的変更を管理するために使用されるアプローチです。AppFlowの配信モデルに似ています。

例

• App v1.x (100,000 users) → production チャンネル
• App v2.x (50,000 users with breaking changes) → 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
    }
  }
};

Step 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

Step 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 アプリのインストール済みバンドル内にあります。JavaScriptのcodeの変更は必要ありません!

利点

• ゼロのcodeの変更 - チャンネルルーティングは自動的に行われます
• 明確な分離 - 各バージョンには独自のアップデートパイプラインがあります
• 柔軟なターゲット - 特定のバージョングループにプッシュアップデートを送信します
• 安全なロールアウト - 不相応のバージョンには、変更点が届きません

戦略 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
• までの更新を受け取る ユーザーは NO 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) を実行する場合にのみ機能します。アプリのバージョンに MAJOR.MINOR.PATCH を使用してください。バージョン番号が

Strategy 3: Native Version Constraints

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

Using nativeVersion Delay Condition

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

# 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"

4. 自動ダウングレード防止戦略

ユーザーが古いバージョンのネイティブアプリケーションをインストールしないようにします。

チャンネル設定で有効

Capgo ダッシュボードに移動してください

1. Go to チャンネル → チャンネルを選択
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' })
  }
}

デバイスオーバーライドダッシュボード

Capgo ダッシュボード内で:

1. 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. バージョン 1 とバージョン 2 の両方にアップデートをプッシュする

# 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 ダッシュボードを使用して、以下を追跡する

• バージョン 1 とバージョン 2 のユーザーの数
• バージョンごとの採用率
• バージョンごとのエラーまたはクラッシュ

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. Default Channel (Cloudflare設定) - 最低優先順位

優先順位の例

ユーザーのアプリが defaultChannel: 'v2' しかし、ユーザーのデバイスをオーバーライドすると 'beta' ダッシュボードで更新を受け取る 'beta' チャンネル。

デバイスのオーバーライドUIは、ダッシュボードまたはパブリック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. リリース前にテストする

# 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. バージョン分布を監視する

ユーザーが最新のネイティブバージョンにアップグレードしているかどうかを確認してください:

• __CAPGO_KEEP_0__
• 古いバージョンはまだ高トラフィックを受けているのですか?
• 古いチャネルを非推奨にするべきですか?

Ionic AppFlowと比較

Ionic AppFlowからチームが移行する場合 Ionic AppFlowからチームが移行する場合、__CAPGO_KEEP_0__のバージョン対象機能はどのように比較されますか?, here’s how Capgo’s version targeting compares:

Ionic AppFlow	__CAPGO_KEEP_0__	Capgo
ネイティブのバージョンに基づいて自動的に設定される	Ionic AppFlowと__CAPGO_KEEP_0__のバージョン対象機能の比較	自動で defaultChannel + 多くの戦略
シーケンスバージョン	基本的なサポート	高度な --disable-auto-update (メジャー/マイナー/パッチ)
ネイティブバージョン制約	AppFlow ダッシュボードで手動で設定	組み込み --native-version flag in CLI
チャンネル管理	Web UI + CLI	Web UI + CLI + API
デバイスのオーバーライド	デバイスの制御が限られている	フルコントロール用ダッシュボード/API
ダウンレートの自動防止	あり	あり --disable-downgrade
複数バージョンのメンテナンス	マニュアルブランチ/チャンネル管理	チャンネル順位による自動化
自主ホスティング	なし	Yes (full control)
バージョン分析	Basic	バージョンごとの詳細なメトリクス

AppFlowのパリティと超え

Capgoは AppFlowが提供したバージョン対象機能のすべて、さらに制御機構が付いたものです。AppFlowの自動バージョンマッチングに依存していた場合、__CAPGO_KEEP_0__は安全で柔軟性が高くなります。 that AppFlow offered, plus additional control mechanisms. If you relied on AppFlow’s automatic version matching, you’ll find Capgo equally safe with more flexibility.

トラブルシューティング

targetLanguage

確認する:

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. ネイティブバージョンを確認: 確認 --native-version __CAPGO_KEEP_0__

古いバージョンに影響を与える変更点

1. 直ちな修正: 影響を受けたデバイスを安全なバンドルに置き換えます
   • ダッシュボード → デバイス → 一括選択 → バージョンを設定
2. 長期的な修正: バージョン管理されたチャンネルを作成し、別々のブランチを維持します
3. 予防: 更新をロールアウトする前に、代表的なデバイスでテストする

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

Ionic AppFlowから移行している場合 __CAPGO_KEEP_0__のバージョン対象は、より柔軟性が向上した__CAPGO_KEEP_0__と非常に似ています:, version targeting works very similarly in Capgo, with improved flexibility:

セクション「概念マッピング」

__CAPGO_KEEP_0__の同等	Capgo Equivalent	デプロイチャネル
__CAPGO_KEEP_0__チャネル	Capgo Channel	ネイティブバージョンロック']}
protectedTokens	--native-version flag	More granular control
Channel Priority	Channel precedence (override → cloud → default)	More transparent precedence
Deployment Target	Channel + semver controls	Multiple strategies available
Production Channel	production channel (or any name)	Flexible naming
Git-based deployment	CLI バンドルアップロードからブランチ	同様のワークフロー
自動バージョンマッチング	defaultChannel + バージョン制約	複数の戦略を組み合わせた強化

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

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

Migration Steps

1. AppFlowチャンネルをマップする Capgoチャンネル (通常 1:1) に
2. Set defaultChannel バージョン capacitor.config.ts for each major version
3. 各メジャーバージョン Configure semver rules
4. バージョンごとのバンドルをアップロード を使用して --native-version フラグ
5. バージョン分布を監視 in Capgo dashboard

マイグレーション ガイド

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 provides multiple strategies for version-specific update delivery:

1. バージョンごとの段階的なロールアウト: 自動バージョン分離 defaultChannel
2. Semantic Versioning: メジャー/マイナー/パッチ境界を超えた更新を防止
3. Native Version Constraints: バンドル用の最低限のネイティブバージョンを要求
4. Auto-Downgrade Prevention: 新しいネイティブバージョンに古いバンドルを配信しない
5. Device Overrides: テストとターゲット設定のための手動制御

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

詳細な特定の機能については:

• Breaking Changes Guide - 詳細チャネルバージョニング戦略
• チャネル管理 - チャネル構成の完全な参照
• 更新動作 - ネイティブバージョン遅延と条件

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

Capgoを使用している場合 バージョン目標 チャネルルーティングとステージドロールアウトの計画に使用し、チャネルと接続してください。 チャネル チャネル チャンネル __CAPGO_KEEP_0__ チャンネル __CAPGO_KEEP_0__ ベータテスト ソリューション __CAPGO_KEEP_0__ バージョン ターゲット ソリューション __CAPGO_KEEP_0__