下位互換性の有効化

​

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

​

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

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

​

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

​

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

npm install @amazon-devices/kepler-compatibility

​

互換性要件の定義

  {
    "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.0.0などになります。この値は、申請時点で動作確認済みの最も高い値に設定してください。

​

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

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 />;
  }
}

​

テストと検証

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

​

例

​

新機能のサポートの追加

  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のバージョンが、ターゲットデバイスで利用可能なバージョンよりも高くなっていないことを確認します。

​

実行時のエラー

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

​

テストの問題

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

​

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

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