Capgoバージョン名は、最初は逆に感じるかもしれません： version_build はネイティブアプリのベースラインであり、 version_name デバイス上の bundle を追跡します。この違いを正しく理解すれば、ロールアウトする前に、デバイスが OTA アップデートを受け取る／受け取らない理由を確認できます。
自社を含む 5 つの Live Update プラットフォームのトラブルシューティングページを分析したところ、当社のドキュメントには version_build の不一致コードが 7 つ記載されていました（他の 4 社は 5、2、2、0）。名前付きコードが多いほど、version_build の不一致が起きたときの推測が減ります。
目次
- ステップ 1: Capgo 内の version_build と version_name を確認する
- ステップ 2: ネイティブのベースラインとダウンロード済みの bundle を特定する
- ステップ 3: ネイティブアプリのバージョンがどこから来ているかを確認する
- ステップ 4: Capgo が受信する bundle バージョンを設定・検証する
- ステップ 5: アップデートを配信する前に、チャネルの対象条件をテストする
- ステップ 6: バージョンの不一致を診断し、リリースを再現可能にする
- よくある質問
- まとめ
ステップ 1: Capgo 内の version_build と version_name を確認する
まず、これらを「1つのアプリインストールに関する2つの異なる事実」として捉えましょう。 version_build デバイス上のネイティブアプリのバージョンを Capgo に伝えます。 version_name デバイスがダウンロードした JavaScript bundle を Capgo に伝えます。これらは異なる値になることがあり、多くの場合それは想定どおりです。
Capgo のバージョンモデルでは、ネイティブバージョンが更新対象かどうかの基準になります。Capgo は、チャネルに割り当てられたバンドルをそのネイティブベースラインと比較します。デバイスにインストールされているバンドルバージョンは、現在の Web code を特定するのに役立ちますが、チャネルのバージョンルールにおけるネイティブベースラインを置き換えるものではありません。
トラブルシューティングの前に、Capgo コンソールの Devices ページでデバイスを検索し、両方の値を記録してください。その後、チャネルのターゲットバンドルと比較します。 Capgo チャネルルール チャネルのターゲットバージョンがどのように照合されるかを説明します version_build.
| 値 | 何を表すか | これに答える用途 | 典型的なソース |
|---|---|---|---|
version_build |
Capgo に送信されたネイティブアプリのベースライン | このネイティブアプリは、チャネルのターゲットバンドルを受信できますか？ | ネイティブアプリのバージョン、または明示的な Capacitor 設定値 |
version_name |
現在ダウンロードされている JavaScript バンドル | 現在インストールされているバンドルバージョンはどれですか？ | アップロード時に解決されたバンドルバージョン |
| チャネルのターゲット | デバイスのチャネルに割り当てられたバンドル | Capgo はどのバージョンの更新を確認していますか？ | 現在のチャネル割り当て |
リリースノートやテストレポートでは、3つの値を別々の列に保持してください。チームが単一の汎用的な「アプリバージョン」を記載すると、誤ったペアを比較してしまいがちです。適格性の判定では、ターゲットのバンドルを以下と比較します。 version_build。インストール済みのWeb code を確認するには、 version_name.
Capgo の命名は、Androidの慣習とは異なって見えるかもしれません。Androidではチームが「build」をインクリメントするビルド番号を意味するために使うことがよくあります。ここでは、名前が示唆するものではなく、その Capgo の役割に基づいてフィールドを読み取ってください。この小さな習慣が、リリース時の多くの混乱を防ぎます。
ステップ 2: ネイティブのベースラインとダウンロード済みの bundle を特定する
バージョン値を変更する前に、どの code がネイティブで、どの code がバンドルとして配信されるかを特定してください。ネイティブアプリは、インストールされたiOSまたはAndroidのバイナリです。バンドルには、Capacitor アプリがOTA更新を通じて受信できるWebアセットが含まれます。
ベースラインが 1.2.3のネイティブアプリがリリースされたと想像してください。その後、Webの修正がバンドル 1.2.4としてアップロードされます。Capgo は、チャネルのターゲットバンドルがネイティブベースライン 1.2.3に対して許可されているかを確認します。適格であれば、デバイスはそのバンドルをダウンロードできます。インストール後、 version_name はデバイス上の現在のバンドルを反映します。ネイティブベースラインは、インストールされたバイナリに紐付いたままです。
ユーザーが古いアプリストア版のビルドを使用しているが、Webバンドルは新しい場合、この違いが重要になります。バンドルはネイティブバイナリを置き換えることなく変更できますが、OTAアップデートでは、アプリに含まれていなかったネイティブのcodeを追加することはできません。新しいプラグインやネイティブ設定が必要な変更がある場合は、バンドルアップロードの代わりとしてネイティブビルドを計画してください。
値が同期していないように見える場合は、このクイックチェックを使用してください：
- テストデバイスにインストールされているネイティブバイナリを確認します。
- Capgoがネイティブベースラインとして受け取るバージョン値を特定します。
- デバイスのチャンネルに割り当てられた bundle バージョンを確認します。
- インストール済みの bundle バージョンは、両方とは別に記録します。
ネイティブベースラインを次から推測しないでください package.json ビルドプロセスがその値をネイティブバージョンまたは Capgo 設定に意図的にコピーしない限り。JavaScript プロジェクトのバージョンとストアにインストールされたアプリのバージョンはずれることがあります。正しいソースは、アプリが実際に Capgo に送信している値です。
ベースラインと現在の bundle を特定できたら、次は各値をソースファイルまでたどることです。プラットフォームごとの違いが出やすいのはここです。
ステップ 3: ネイティブアプリのバージョンがどこから来ているかを確認する
信頼できる version_buildためには、Capacitor アプリが報告するネイティブバージョンを特定します。Capgo のバージョンドキュメントでは iOS と Android で異なるソースキーが説明され、その結果得られるネイティブ値を OTA 比較のベースラインとして使用します。
iOSの場合
確認 CFBundleShortVersionString アプリの Info.plist。ほとんどの Xcode プロジェクトでは、このキーは以下に設定されています $(MARKETING_VERSION)、実際に編集するのはターゲットのマーケティングバージョンです。テンプレートや、ビルドで上書きされる可能性のあるファイルだけでなく、ビルドしたアプリで値を確認してください。
チームが Xcode プロジェクトを更新しても、アプリに反映される値を更新しないと、ローカルのプロジェクト表示は正しく見えても、インストール済みバイナリが別の値を示します。生成されたネイティブアプリのバージョンと、リリースプロセスが期待する値を比較してください。
Androidの場合
確認 defaultConfig.versionName Android アプリの Gradle 設定にあります。このネイティブバージョン名は Capgo の OTA 比較で使用されます。Android のビルド code や無関係な JavaScript パッケージのバージョンと混同しないでください。このチェックで重要なのは、ネイティブアプリが送信するバージョン名が何かです。
バージョンポリシーを共有すれば両プラットフォームを揃えやすくなりますが、すでに同じソースを共有していると決めつけないでください。iOS と Android では、ファイル、ビルド手順、リリースタイミングが別々になる場合があります。特に一方のプラットフォームでストアのロールアウトスケジュールが異なる場合は、リリースチェック時に最終的な値を比較してください。
一部のアプリは、ネイティブバージョンを明示的に設定しています capacitor.config.ts updater 設定の version 値を通じて。 Capgo Semver テスター このネイティブベースラインは、設定またはネイティブアプリのメタデータから取得できる値として説明されています。アプリがネイティブメタデータをオーバーライドする場合は、その選択を文書化し、ストアのバージョンがソースであるという誤解を招かないようにしてください。
各プラットフォームについて、ソースファイル、解決された値、およびそれを含むビルドを記録してください。これにより、リポジトリにテストデバイスのアプリより新しいバージョンが含まれている場合でも、リリース後の不一致を追跡しやすくなります。
ビルドが実際に読み取るソースのみを変更してください。古いファイルを編集すると、code のレビューが完了したように見えますが、パッケージ化されたネイティブバージョンは変更されないままになる可能性があります。
ステップ 4: Capgo が受信する bundle バージョンを設定・検証する
バンドルバージョンは、インストールされたネイティブバイナリではなく、JavaScript の更新を説明します。Capgo は、そのバージョンを version フィールド（ package.json から取得できます（明示的なバンドルバージョンを指定しない場合）。CLI の --bundle オプションは、アップロード時に送信されるバージョンを設定できます。
1つのパスを選択し、リリースプロセスで明確にしてください。 package.json がソースである場合は、アップロード前にそのフィールドをインクリメントしてください。CI が CLI を通じてバンドルバージョンを渡す場合は、ジョブがリリースログに解決されたバージョンを出力するようにしてください。両方のパスが静かに混在すると、チャネルが特定の値を受信した理由を特定しにくくなります。
慣れ親しんだ形式でセマンティックバージョニングを使用する major.minor.patch 例えば、 1.2.3。Capgo のチャネル戦略は、そのバージョンの各要素に基づいて、ターゲットのバンドルがネイティブベースラインに適合するかを判断します。プレリリースサフィックス（例： -beta.1 ）はチャネル固有のビルドにラベルを付けるのに役立ちますが、リリースツール全体でバージョンがパース可能かつ一貫性があることを保ってください。
公開前にインクリメントの種類を検討してください：
- 同じリリースライン内の互換性のあるWeb修正には、パッチ変更を使用します。
- 互換性のある新しい機能ラインに属する変更なら、マイナー変更にしてください。
- 互換性の境界が変わり、古いネイティブ code がbundleをサポートしない可能性がある場合は、メジャー変更にしてください。
これらのラベルはチームの規約であり、OTAでネイティブ機能を追加する手段ではありません。バージョン番号だけでは、bundleがネイティブアプリに対して安全であることを証明できません。実際の互換性の判断は、バイナリ内の code と依存関係に基づけてください。
uploadする前に、パッケージのバージョンまたは CLI の値と、upload後に表示されるbundleのバージョンを比較してください。また、配信先のchannelも確認してください。正しく命名されたbundleでも、意図しないchannelにuploadすると、誤ったテスト結果につながる可能性があります。
無効または不整合な文字列は、推測せず一度立ち止まって確認すべきです。正常動作が確認済みのリリース値を保持し、ソースを修正してから、昇格前に解決後のバージョンをテストしてください。
この Capgo CLI コマンドリファレンス bundleのバージョンがリリースコマンドの入力の一部になるため、uploadをスクリプトに組み込む場合に便利です。
ステップ 5: アップデートを配信する前に、チャネルの対象条件をテストする
channelの適合性は比較で決まり、どのbundleが新しく見えるかによる推測ではありません。Capgo は、channelのターゲットbundleを、として送信されるネイティブのベースラインと比較します： version_build現在ダウンロードされているbundle（次のように報告されます： version_name）は、それらのchannelルールのベースラインにはなりません。
例えば、インストール済みのネイティブアプリが報告する値が 1.2.3で、現在のバンドルが 1.2.4。チャンネルが 1.2.5を指している場合は、ネイティブのベースラインに対してターゲットを評価します 1.2.3（現在のバンドルだけに対してではなく） 1.2.4。どのターゲットが許可されるかは、チャンネルのアップデート戦略によって決まります。
Capgo では、ネイティブのベースラインに対してアップデートを制限する major や minor などの戦略について説明しています。major 戦略では、メジャーバージョンがより高いターゲットがブロックされる可能性があります。minor 戦略では、ベースラインのメジャーまたはマイナーラインを変更するターゲットがブロックされる可能性があります。新しく見えるバンドルがすべて受け入れられると決めつけず、設定されている戦略を確認してください。
リリース予定の正確な組み合わせをテストしてください：
- ターゲットとなるユーザーが使用している Native Build をインストールします。
- Capgo に送信されたネイティブのベースラインを確認します。
- テストデバイスを対象のチャンネルに割り当てます。
- チャネルのターゲットとそのバージョン戦略を確認します。
- 更新をリクエストし、デバイスの結果を確認します。
ユーザーベースに複数のストアバージョンが存在する場合、別のネイティブベースラインでも同じチェックを実行してください。新しいビルドでは動作するバンドルが、古いバイナリではブロックされる場合があります。これは意図されたセーフティルールである可能性があります。
より広いリリースでは、テストチャネルや限定ロールアウトから開始してください。対象範囲を拡大する前に、予期しない適格性結果に注意を払ってください。Capgo のチャネルモデルにより、チームはリリースチャネルを通じてバンドルを配信できます。リリースノートでは、各チャネルのターゲットと意図されたネイティブラインを明確にしてください。
テストデバイスが更新されない場合は、再アップロード前にチャネル割り当てとバージョン値を確認してください。同じバンドルを繰り返し公開しても、ベースラインの不一致は修正されません。
ステップ 6: バージョンの不一致を診断し、リリースを再現可能にする
値が期待通りでない場合は、順序を追ってトレースしてください。まず、デバイス上のネイティブアプリのバージョンを確認します。次に、設定のオーバーライドがベースラインを変更していないか確認します。その後、Capgo が受け取ったバンドルバージョンとチャネルのターゲットを比較します。この手順により、ソース値の問題と、設定どおり動作しているチャネルルールを区別できます。
一般的な原因には、bump（バージョン番号の引き上げ）が含まれます。 package.json ネイティブバージョンは変えずに、別のリリースブランチから片方のプラットフォームをビルドし、さらに別のチャネルに割り当てられたデバイスでテストするといった状況です。もう1つの混乱の元は、すべての数値を「ビルドバージョン」と呼ぶことです。どの値がネイティブのものか、どれがアップロード済みのbundleか、どれが現在インストールされているものかを書き留めておきましょう。
CI/CDでは、バージョンの入力を明示します。パイプラインが管理されたソースから意図したリリースバージョンを読み取り、アップロードコマンドに渡すか、アップロードステップの前にpackageフィールドを更新するようにします。確定したネイティブベースラインとbundleターゲットをジョブ出力に記録します。ビルドサーバーから見えない開発者のローカル状態に依存しないようにします。
必要なバージョンがない、またはチームが受け入れない形式の場合に失敗するリリースゲートを使います。その後、プロモーション前に正しいチャネルへテストアップロードを実行します。CapgoはCLIベースのデプロイフローをサポートしているため、チームは既存のCI/CDジョブにbundleのアップロードを組み込み、コマンドログを可視化したまま残せます。
これらの値をAndroid WebViewエンジンのバージョンと混同しないでください。当社の @capgo/capacitor-webview-version-checker プラグインは、デバイスのWebViewエンジンが古くなっていないかを確認し、ネイティブのアップデートプロンプトを表示できます。これは、 version_build と version_nameとは別の問題であるため、ネイティブベースラインとチャネルのターゲットbundleの確認に代わるものではありません。
レガシーなスキームから移行する場合、既存の値を一度にすべてリネームしないでください。まず、古いネイティブバージョンをネイティブのベースラインにマッピングします。次に、アップロードされたWebリリースをbundleバージョンにマッピングします。ユーザーに配信する前に、既存の代表的なアプリビルドをチャンネル戦略に対してテストしてください。
ソースコミット、ネイティブバージョン、アップロードされたbundleバージョン、チャンネル、テスト結果をまとめた簡単なリリース記録を残してください。リリースを一時停止したりロールバックしたりする必要がある場合、この記録があればチームはどのbundleがどこに配信されたかを特定できます。また、誰かがどのファイルを変更したかを覚えていることに依存せず、次回のデプロイを再現可能にします。
よくある質問
Capgo における version_build と version_name の違いは何ですか？
version_build はネイティブアプリのベースラインであり、 version_name は現在ダウンロードされているbundleバージョンです。Capgo は、チャンネルのターゲットbundleが対象かどうかをチェックする際にネイティブのベースラインを使用します。どのネイティブアプリがインストールされていて、どのWeb bundleが適用されているかを判別できるよう、ログとリリースノートではこの2つの値を分けておいてください。
version_name は OTAアップデートを許可するかどうかを制御しますか？
いいえ、Capgo のチャンネルバージョン戦略は、ターゲットbundleを version_build、つまりネイティブのベースラインと比較します。 version_name は現在ダウンロードされているbundleを特定します。デバイスにアップデートが届かない場合は、現在のbundleの値を変更する前に、そのベースライン、チャンネルターゲット、設定された戦略を確認してください。
Capgo はネイティブバージョンをどこから取得しますか？
iOS では、Capgo は以下を読み取ります： CFBundleShortVersionString内）。通常、Xcode がここから入力します MARKETING_VERSION。Android では、ネイティブバージョンは次から取得します defaultConfig.versionName。Capacitor の設定でアップデータバージョンを明示的に指定すると、アプリが送信する値が変わる場合があります。ビルドしたアプリで確認してください。
Capgo はバンドルバージョンをどこから取得しますか？
Capgo は次を使用できます version フィールド（ package.json 明示的なバンドルバージョンを渡さない場合。また、CLI の --bundle オプションでバージョンを指定することもできます。リリースワークフローで明確なソースを1つ選び、アップロード後に Capgo が受け取ったバージョンを確認してください。
まとめ
使用する version_build ネイティブベースライン用と version_name インストール済みバンドル用。次のロールアウト前に、テストデバイスで両方の値を確認し、チャネルターゲットとベースラインを比較してください。この1つのチェックで、より広いユーザー層に届く前にバージョン不一致を検出できます。
