Enable Backward Compatibility

​

About system distributed libraries

​

Use the compatibility library

​

Install compatibility library

npm install @amazon-devices/kepler-compatibility

​

Add version checks in code

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

// In this example, this new feature was introduced in 2.2.0
const supportsNewGesture = useMemo(
  () => isPresentOnOS("@amazon-devices/react-native-gesture-handler", "2.2.0"),
  []
);

function MyComponent() {
  // Check if newer version is available before using new-released features
  if (supportsNewGesture) {
    // Use new 2.2.0 features
    return <GestureHandler.NewFeature />;
  } else {
    // Fallback for devices without 2.2.0
    return <GestureHandler.LegacyFeature />;
  }
}

​

Testing and verification

1. Use Vega to install different simulators: use the CLI to install device simulators on older and newer versions, which will help simulate different real-world scenarios of pre-installed system distributed libraries.
2. Install the app.
3. Verify that the app works as expected, paying special attention to any version checks and fallback implementations for older versions, to ensure they are functioning correctly.

​

Example

​

Add support for a new feature

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

function DraggableItem() {
  if (isAppTargeting("@amazon-devices/react-native-gesture-handler", "2.1.0")) {
    // New implementation using 2.1.0 features
    return (
      <GestureHandler.DragGesture
        withNewBehaviors={true}
        onDragStart={handleDragStart}
      >
        <Item />
      </GestureHandler.DragGesture>
    );
  }

  // Fallback implementation for 2.0.0
  return (
    <GestureHandler.PanGesture
      onGestureEvent={handleLegacyDrag}
    >
      <Item />
    </GestureHandler.PanGesture>
  );
}

​

Troubleshooting

​

Common issues

​

Version mismatch

• Problem - The app fails to install on some devices.
• Solution - Verify that your [os.version].min value in manifest.toml isn’t higher than the OS version on your target devices. For details, see Manifest [os.version] Section.

​

Runtime errors

• Problem - Features crash on certain devices.
• Solution - Ensure you wrap all new feature usage in version checks.

​

Testing issues

• Problem - It’s difficult to test across versions.
• Solution - Use the device simulator to test with different system versions.

​

Performance best practices with version check

1. Always check versions as early as possible in your component lifecycle.
2. Cache version check results to avoid repeated checks.
3. Consider creating utility functions for commonly checked feature sets, as shown in this example below.
   // Utility function example
   import { isAppTargeting } from '@amazon-devices/kepler-compatibility';
   
   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 {
       // Return an object of supported features based on version
       supportsHoverGesture: featureSupport.hasGestures2_1,
       supportsPinchToZoom: featureSupport.hasGestures2_1,
       // Add other feature flags as needed
     };
   }
   
   // Usage in a Component in App
   function MyGestureComponent() {
     const features = getGestureHandlerFeatures();
   
     if (features.supportsHoverGesture) {
       return <HoverEnabledComponent />;
     }
     return <StandardComponent />;
   }