Console

Settings

Sign out

Notifications

Alexa

Amazonアプリストア

AWS

ドキュメント

Support

My Cases

Console

Vega開発者向けドキュメント

ホーム

開発

設計と開発

公開

リファレンス

サポート

下位互換性の有効化

オープンベータ版ドキュメント：本テクニカルドキュメントは、リリース前のオープンベータ版の一部としてAmazonから提供されるものです。ここで説明されている機能は、Amazonがフィードバックを受け取り、機能の開発を繰り返す過程で変更される可能性があります。最新の機能の情報については、リリースノートを参照してください。

アプリを初めてリリースするときは、下位互換性が問題になることはありません。ただし、新しいバージョンの@amazon-devices/システム配布ライブラリを使用するようにアプリをアップデートし、Amazonアプリストアに再申請すると、これらのライブラリの以前のバージョンが搭載されているデバイスでは、最新のアプリバージョンのインストールやアップデートを行うことができなくなります。

Vega向けReact Nativeには、これらのライブラリの古いバージョンと新しいバージョンをアプリで同時にサポートできるようにする、オプトインの下位互換性機能が用意されています。この機能は、幅広いユーザーベースを維持し、さまざまなシステムバージョンで一貫したエクスペリエンスを提供するために不可欠です。

システム配布ライブラリについて

システム配布ライブラリとは、アプリのサイズと読み込み時間を最適化するために、デバイスにプリインストールされているJavaScriptパッケージです。これらには常に@amazon-devices/というプレフィックスが付いています。

下位互換性に関して、これらの各ライブラリのバージョンは、デバイスが新しいフラッシュアップデートまたはOTAアップデートを受け取るまで変わりません。

システム配布ライブラリの新しいバージョン（2.1.0など）がリリースされた場合、Vega向けReact Nativeは、同じメジャーバージョン内の以前のバージョン（2.0.0など）との互換性を維持します。

オプトインとオプトアウト

アプリをアップデートするときに、下位互換性をオプトインするかオプトアウトするかを選択できます。

オプトアウトすると、アプリはシステム配布ライブラリの最新バージョンのみをサポートすることになるため、開発とテストを簡素化できます。ただし、これらのライブラリの以前のバージョンを実行しているデバイスにはアプリをインストールできなくなります。

下位互換性をオプトインすると、コードと構成に追加の変更が必要になりますが、大きなメリットを得ることができます。

より幅広いデバイスのサポート - 以前のシステムバージョンのデバイスでもアプリを実行できます。
新機能へのアクセス - 以前のバージョンをサポートしながら、新しいライブラリ機能を使用できます。
1回限りのアプリの申請 - 1回のデプロイで複数のシステムバージョンをサポートできます。
自動検証 - インストール前にシステムによって互換性が検証されます。

下位互換性をオプトアウトする正当な理由としては、たとえば、メジャーバージョンアップデートで互換性にかかわる重要な変更を導入する場合があります。ほとんどのユースケースでは、アプリのリーチを最大化するために下位互換性を保つことをお勧めします。

下位互換性サポートの構成

互換性ライブラリのインストール

ライブラリをインストールするには、次のコマンドを実行します。

クリップボードにコピーしました。

npm install @amazon-devices/kepler-compatibility

互換性要件の定義

アプリ内で使用されるライブラリの下位互換性を指定するには、package.jsonのkeplerブロックのbackwardCompatibilityに、ライブラリの名前とそのneedsおよびwantsを追加する必要があります。また、互換性ライブラリをdependenciesセクションに追加する必要もあります。

クリップボードにコピーしました。

  {
    "name": "MyApp",
    "version": "1.0.0",
    "dependencies": {
      "@amazon-devices/kepler-compatibility": "^0",
      "@amazon-devices/react-native-gesture-handler": "2.4.0"
    },
    "kepler": {
      "backwardCompatibility": {
        "@amazon-devices/react-native-gesture-handler": {
          "needs": "2.0.0", // サポートされる最小バージョン
          "wants": "<=2.4.0" // サポートされる最大バージョン
        }
      },
      ...
    }
  }

needs - アプリで使用できる最小バージョン。値には正確なSemVerバージョンを指定する必要があります。アプリを実行するために存在している必要のあるバージョンを表します。デバイスにこれらのモジュールがない場合、アプリをインストールすることはできません。
wants - アプリで使用できる最大バージョン。値はneedsを含むSemVer範囲に設定する必要があります。たとえば、上記の範囲に対して有効なwantsは、<2.5.0、<=2.2.0、^2.0.0などになります。この値は、申請時点で動作確認済みの最も高い値に設定してください。

コードへのバージョンチェックの追加

isPresentOnOS APIは、必要なライブラリバージョンがシステムにインストールされているかどうかを実行時に確認するために役立ちます。これは、コードが特定の古いバージョンに依存している場合や、新しいバージョンでのみ使用できる機能を必要としている場合に特に重要です。

クリップボードにコピーしました。

import { isPresentOnOS } from '@amazon-devices/kepler-compatibility';
import * as GestureHandler from '@amazon-devices/react-native-gesture-handler';

// この例では、この新機能を2.2.0で導入したと仮定します。
const supportsNewGesture = useMemo(
  () => isPresentOnOS("@amazon-devices/react-native-gesture-handler", "2.2.0"),
  []
);

function MyComponent() {
  // 新しくリリースされた機能を使用する前に、新しいバージョンが使用可能かどうかを確認します。
  if (supportsNewGesture) {
    // 2.2.0の新機能を使用します。
    return <GestureHandler.NewFeature />;
  } else {
    // 2.2.0を使用できないデバイス用のフォールバック。
    return <GestureHandler.LegacyFeature />;
  }
}

テストと検証

アプリを申請する前に、backwardCompatibilityブロックに指定したシステム配布ライブラリの古いバージョンと新しいバージョンが搭載された各デバイスで、十分なテストを行うことが重要です。

テスト手順

Vegaを使用して複数のシミュレーターをインストールします。CLIを使用して古いバージョンと新しいバージョンのデバイスシミュレーターをインストールすると、プリインストールされたシステム配布ライブラリの実際的な複数のシナリオをシミュレートできます。
アプリをインストールします。
アプリが期待どおりに動作することを確認します。バージョンチェックと古いバージョン用のフォールバック実装に特に注意して、それらが正しく機能していることを確認します。

例

新機能のサポートの追加

以下の例では、@amazon-devices/react-native-gesture-handlerのDragGestureに、仮想的にwithNewBehaviors属性のサポートを追加する方法を示します。これにより、従来のPanGestureの実装から切り替えつつ、以前の実装を残して古いライブラリバージョンとの下位互換性を維持できます。

クリップボードにコピーしました。

  import { isAppTargeting } from '@amazon-devices/react-native-kepler';
  import * as GestureHandler from '@amazon-devices/react-native-gesture-handler';

  function DraggableItem() {
    if (isAppTargeting("@amazon-devices/react-native-gesture-handler", "2.1.0")) {
      // 2.1.0の機能を使用する新しい実装
      return (
        <GestureHandler.DragGesture
          withNewBehaviors={true}
          onDragStart={handleDragStart}
        >
          <Item />
        </GestureHandler.DragGesture>
      );
    }

    // 2.0.0用のフォールバック実装
    return (
      <GestureHandler.PanGesture
        onGestureEvent={handleLegacyDrag}
      >
        <Item />
      </GestureHandler.PanGesture>
    );
  }

トラブルシューティング

よくある問題

よくある問題とその解決策を以下に示します。

バージョンの不一致

問題 - 一部のデバイスでアプリのインストールに失敗する。
解決策 - needsのバージョンが、ターゲットデバイスで利用可能なバージョンよりも高くなっていないことを確認します。

実行時のエラー

問題 - 特定のデバイスで機能がクラッシュする。
解決策 - 新機能を使用しているすべての箇所で、バージョンチェックが行われていることを確認します。

テストの問題

問題 - 複数のバージョンでテストするのが難しい。
解決策 - 異なるシステムバージョンでテストを行うには、デバイスシミュレーターを使用します。

バージョンチェックのパフォーマンスに関するベストプラクティス

バージョンチェックは常に、コンポーネントライフサイクルのできるだけ早い段階で行います。
バージョンチェックの結果をキャッシュして、チェックを繰り返さないようにします。
よくチェックする機能セットには、以下に示すようにユーティリティ関数を作成することを検討します。

クリップボードにコピーしました。

// ユーティリティ関数の例
  const featureSupport = {
    hasGestures2_1: null as boolean | null,
  };

  export function getGestureHandlerFeatures() {
    if (featureSupport.hasGestures2_1 === null) {
      featureSupport.hasGestures2_1 = isAppTargeting(
        "@amazon-devices/react-native-gesture-handler",
        "2.1.0"
      );
    }

    return {
      // バージョンに基づいて、サポートされる機能のオブジェクトを返します。
      supportsHoverGesture: featureSupport.hasGestures2_1,
      supportsPinchToZoom: featureSupport.hasGestures2_1,
      // 必要に応じてその他の機能フラグを追加します。
    };
  }

  // アプリ内のコンポーネントでの使用例
  function MyGestureComponent() {
    const features = getGestureHandlerFeatures();
    
    if (features.supportsHoverGesture) {
      return <HoverEnabledComponent />;
    }
    return <StandardComponent />;
  }

Last updated: 2025年10月30日