[os.version]セクションを追加する必要がある場合は、既存のアプリのアップグレードから始めてください。アプリがさまざまなOSバージョンをサポートしている場合は、isPresentOnOSによる新しいAPIのガードを参照して、新しいAPIを安全に採用する方法を確認してください。
特定のOSバージョンが提供するAPIを確認するには、Vega APIリファレンスを参照してください。サポートされているサードパーティのライブラリのバージョンについては、サポート対象のサードパーティのライブラリとサービスを参照してください。
OSバージョンとSDKバージョンの比較
次の表に示すように、OSバージョンとSDKバージョンは異なる2つの概念です。
このページの残りの部分では、OSバージョンについて説明します。
バージョン互換性マトリックス
次の表は、React Nativeランタイム、各Vega SDKバージョンが対応するデバイスOSバージョン、およびビルド可能なホストマシンを示しています。- 導入先となるOSのバージョンは、各SDKバージョンが付属していたデバイスOSのバージョンです。現在、すべてのVegaデバイスはすべてのOSアップデートを受信できているため、現場のデバイスは利用可能な最新のOSを実行しています(これは将来変更される可能性があります)。
- サポート対象のホストマシンは、Vegaアプリを構築できる開発マシンです。Windowsはサポート対象のビルドホストではありません。Intel Macのサポートは2026年12月15日に終了します。
OSバージョンとReact Nativeランタイム
各OSバージョンには1つ以上のReact Nativeランタイムが付属しており、アプリはそのうちの1つでのみ実行されます。ランタイムを明示的に設定することはありません。Vega CLIは、package.jsonの@amazon-devices/react-native-*依存関係バージョンからこの情報を読み取るため、プロジェクトが既に依存しているものによってランタイムが決まります。
CLIは、解決したランタイムを出力に反映します。たとえば、📦 Installed packages for OS Version 2.0 + RN 0.72のように出力します。別のランタイムをプレビューするには--rn-versionをvega project installに渡しますが、通常の方法はCLIにpackage.jsonを読み込ませることです。
OS 1.2には、次の表で説明されているように2つのReact Nativeランタイムが用意されています。
RN 0.83はOS 1.2でリリースされたため、0.83ランタイムでビルドされたアプリでは
minを1.2未満に設定できません。以前のOSバージョンには0.83ランタイムは搭載されていません。minがランタイムで必要なOSバージョンよりも低い場合、vega project doctorとビルドで、minを上げるように指示するエラーが出力されます。どちらもこの値を自動的に変更することはありません。
アプリは1つのReact Nativeランタイムに対してビルドされ、常にそのランタイムで実行されるため、実行時にランタイムを判別するガード処理は必要ありません。ビルドツールはこの一貫性を保ち、プロジェクトのランタイムと互換性のない@amazon-devices/*パッケージバージョンに依存することはできません。isPresentOnOSによるランタイムガードは、ランタイムの違いではなく、minバージョンよりも新しいOSバージョンで追加されたライブラリAPIに適用されます。
[os.version]マニフェストセクション
アプリがサポートするOSバージョンの範囲を宣言するには、manifest.tomlに[os.version]セクションを追加します。
-
min- アプリがサポートする最も古いOSバージョン。アプリはこのバージョン以降のどのデバイスにもインストールでき、minで利用可能なAPIを自由に使用できます。 -
target- アプリがビルド対象としている最新のOSバージョン。このバージョンまでに提供されているAPIは使用できますが、minで指定したOSバージョン以降に追加されたAPIを利用する場合は、古いデバイスでもアプリが動作するよう適切なガード処理を行う必要があります。
minとtargetの両方を2.0に設定します。その理由と、代わりにminを1.2に設定するタイミングについては、最小値の選択を参照してください。
SDK 0.24以降では、ビルド時には[os.version]セクションが必須となっています。このセクションがない場合、npx react-native build-vegaでのビルドは失敗します。このセクションは、手作業で追加するか、ツールのvega project update-manifest --os-min 2.0 --os-version 2.0で追加してください。3つの作成方法とそれぞれに必要なフラグについては、マニフェストの [os.version] セクションを参照してください。
このツールは、アプリが利用するOS提供モジュールを、minで利用可能な場合はneedsとして、minとtargetの間で追加された場合はwantsとしてマニフェストに記録します。これらのエントリを手動で記述する必要はありません。ビルドするたびに、これらのエントリは、ソースmanifest.tomlにではなく、検証マニフェスト、ステージマニフェスト、パッケージマニフェストに生成されます。完全なマニフェストの例については、マニフェストの [os.version] セクションを参照してください。エントリ自体の詳細については、マニフェストの [needs] セクションとマニフェストの [wants] セクションを参照してください。
アプリの互換性の設定
OSバージョンの互換性を設定するには、プロジェクトのルートから次のコマンドを実行します。-
vega project install --fixは、@amazon-devices/*の依存関係のOSバージョン互換バージョンをpackage.jsonに解決します。 -
npm installが、解決されたバージョンをインストールします。プロジェクトで既に使用されているパッケージマネージャーを使用してください。 -
vega project doctorは、ビルドの前にプロジェクトを検証します。 -
npx react-native build-vegaはアプリをビルドし、vpkgを生成します。package.jsonで定義されているビルドスクリプトを使用することもできます。
vega projectコマンドは決してnpm、yarn、pnpmを実行しないため、package.jsonを変更するコマンドを実行した後は、独自のパッケージマネージャーを実行してください
doctorは、指定したOSバージョンが有効であり、minがtarget以下であることを確認します。また、パッケージのバージョンが一致していることと、コードで新しいAPIのガード処理が行われていることも確認します。失敗すると0以外の終了コードで終了するため、CIパイプラインで使用できます。完全なオプションの一覧については、vega project doctorを参照してください。
このセットアップチェーンに続く残りのvega projectコマンドは、より限定的なタスクを処理します。新しい@amazon-devices/*パッケージを 1 つ追加するには、vega project install <package>を実行し、パッケージマネージャーを使用してそれをインストールします。別のOSターゲットへの変更を適用する前にその変更をプレビューするには、vega project update --os-version <v> --dry-runを実行します。すべてのコマンドとオプションについては、Vega SDK CLIリファレンスを参照してください。
既存のアプリの更新
動作中のアプリにOSバージョンの互換性を追加するために、何も書き直す必要はありません。-
手書きまたは
vega project update-manifest --os-min 2.0 --os-version 2.0で[os.version]セクションをmanifest.tomlに追加します。 -
vega project install --fixを実行して@amazon-devices/*依存関係をOSターゲットに合わせて再調整します。 -
npm installを実行してからvega project doctorを実行し、プロジェクトに互換性があることを確認します。 - 通常どおりアプリをビルドします。
vega project install --fix --os-min 2.0 --os-version 2.0を実行します。この形式では両方のフラグが必要です。--os-versionがない場合、[os.version] セクションがないプロジェクトのターゲットを解決できず、コマンドは何も書き込まずに失敗します。
既存のコードは引き続き機能します。複数のOSバージョンをサポートする場合は、採用する新しいAPIに対してのみガード処理を追加すれば十分です。
isPresentOnOSによる新しいAPIのガード処理
アプリが複数のOSバージョンをサポートする場合、つまりminがtargetよりも前のバージョンである場合、新しいAPIを導入したライブラリバージョンが古いデバイスには存在しない可能性があります。そのようなAPIへの呼び出しをガード処理していない場合、それらのデバイスでクラッシュが発生します。
この呼び出しをガード処理するには、isPresentOnOSを使用します。これは、実行中のデバイスのOSに特定のバージョン以降のライブラリが存在するかどうかを報告します。
isPresentOnOS(libraryName, version)は次の引数を受け取ります。
-
libraryName- npmライブラリ名。(例:'@amazon-devices/react-native-gesture-handler')。 -
version- semver形式のバージョン文字列(例:'2.2.0')。これはライブラリ独自のバージョンであり、OSバージョンではありません。この関数は、実行中のデバイスのOSが指定されたバージョン以降のライブラリを提供する場合、trueを返します。
isPresentOnOSは@amazon-devices/kepler-compatibilityで提供されています。チェックを繰り返さないようにするには、レンダリングのたびに呼び出すのではなく、結果をuseMemoフックにキャッシュしてください。互換性ライブラリの詳細については、下位互換性の有効化を参照してください。
vega project doctorとVega ESLintプラグインはどちらも、ガードなしで使用される新しいAPIにフラグを立てます。特定のimportに対するチェックを抑制するには、前の行に// @os-version-okコメントを追加します。
ネイティブコードのガード処理
kepler.projectTypeをnativeに設定したプロジェクトでは、vega project doctorはOmniKit IDLインターフェイスでCおよびC++ソースコードが使用されているかどうかもチェックします。OmniKit IDLインターフェイスの唯一のガード処理は、QueryInterfaceまたはTryQueryInterfaceの結果に対するランタイムでのヌルチェックです。OSのバージョンや機能がクエリの条件を満たしていても、このチェック結果が抑制されることはありません。
minでの存在が保証されているインターフェイスにのみQueryInterface<T>()を使用してください。TryQueryInterface<T>()を使用し、インターフェイスが存在しない可能性がある場合はnullptrを確認してください。
1回のネイティブ呼び出しでこのチェックを抑制するには、次のいずれかの位置に// @os-version-okコメントを追加します。ネイティブ位置は、インポート前の行に表示されるJavaScriptの位置とは異なります。
- 呼び出しを行う行の末尾に配置。コメントはその呼び出しのみを抑制します。
- 呼び出しの直前の行にのみ配置。
// do NOT add @os-version-ok hereなどのコメントでもチェック結果は抑制されません。ディレクティブは大文字と小文字を区別し、完全に一致する必要があるため、@OS-VERSION-OKと@os-version-okayは機能しません。
OSバージョン間でのテスト
アプリを申請する前に、minとtargetの両方のOSバージョンでデバイスシミュレーターをインストールし、それぞれでアプリがインストールでき、正常に動作することを確認してください。ガード処理されたコードパスとそのフォールバックに注意してください。

