What's new in SDK v.0.20?

[cebratec]

What’s new in SDK v.0.20?

July 7th 2025, by @Christian_Van_Boven1, @Abhay_Kumar, @Baraks, @pavan, @Michael_Richardson, @Hagen_Last, @ericfahsl, and @cebratec — This blog post and a run down of what’s new within v.0.20 will be discussed during the office hours on 8th July 08:30am PT (03:30pm UTC) and 10th July 08:00am PT (03:00pm UTC)

Today we are thrilled to announce the Release of SDK v.0.20.x (and corresponding device OS update), our launch-ready SDK for the upcoming Amazon Fire TV device. This release represents the culmination of extensive development and testing, including valuable contributions from our partners during existing Beta and BeX (Bleeding Edge) programs. SDK v.0.20 introduces significant enhancements and performance improvements that will empower you to create superior and more immersive experiences for Amazon Fire TV.

Important: SDK 0.20 release will be supported in our new Kepler Fire TV device launch. To ensure your app is ready for the upcoming launch, it is crucial that you build your app with SDK 0.20 or later before submitting your launch-ready app to our Appstore.

OS Bugfix / Release Schedule: To support you in the lead-up to launch, we’re accelerating our bugfix delivery time via a more frequent release cadence. You’ll now receive BeX Releases weekly and regular scheduled OS releases every two weeks. This increased frequency will allow us to deliver critical bug fixes faster as we approach the device launch. If you are interested in the BeX Program, and you are not utilizing it yet, you can contact your Partner SA to opt-in.

Key highlights include: A simplified installation process of the SDK, expanded range of libraries hosted in the OS, new APIs, such as including Restoration Manager and mTLS support, an enhanced version of Headless JS and improved developer tools, featuring a new Simulator called Kepler Virtual Device (KVD). In addition we are releasing new additions of props in React Native for Kepler as well as an ESLint plugin. On the connectivity side, we are releasing an improved HDMI connection event handling and enhanced gaming controller support as part of this SDK.
In addition we have released updates to reference apps (KeplerSportApp, KeplerAudioReferenceApp, KeplerVideoApp, KeplerVoiceControlReference), UI component libraries, bug fixes and performance improvements.

Reminders - Please do not forget

Upgrade Hygiene - w3cMedia Playback

When updating your media player implementation, it’s crucial to maintain version compatibility between the SDK and the react-native-w3cmedia package. For SDK version 0.18, use package version 2.1.59; for SDK 0.19, use 2.1.66; and for SDK 0.20 or higher, implement version 2.1.68 or above.

To ensure optimal performance and access to the latest features, we recommend regenerating your package-lock.json file with each SDK update (including deleting node_modules).

While you can maintain an existing minor version if immediate logic updates aren’t feasible, this approach may limit your access to new enhancements and features. Regular updates will help you leverage the full capabilities of the latest SDK releases, including performance improvements and expanded functionality.

We encourage you to follow this method for all your libraries used and lock dependencies to a certain OS version. We are working on a guidance that is to be published to help with that.

Release Media Resources - Background Mode Limitation

We are introducing a new policy to provide a consistent and seamless user experience when transitioning between media apps. The policy will require apps to release their HtmlMediaElement resources when going to background. If an app fails to do so, it will be terminated . This was previously a recommendation and is turning into an enforcement. We will post additional guidance in form of a Knowledge Base Article that will be available by end of this week.

For Partners that previously opt-in to 0.20 pre-release

For 3P app developers that opted in to receive early versions of the 0.20 release, please complete the following steps:

1. Install the 0.20 official release of the SDK as outlined here: including updating the .npmrc entry for @amzn repositories.

2. Either delete your existing package-lock.json or remove any @amzn references in your package-lock.json to ensure that your application pulls from the release NPM repositories.

What’s new - Release Highlights

Below are new features we are providing as part of the 0.20 SDK update.

Kepler Virtual Device (KVD) - New Developer Experience

A new simulator has arrived. We re-imagined the Simulator and added a remote to it, so the experience is getting closer to using and developing apps on a device directly. While a Simulator will never completely replace testing a scenario on a physical device, we know how important testing on virtual devices are for automated pipelines and fast and scalable development.

The updated simulator enhances your experience with improved User Experience features including boot notifications, in-UI device registration, faster performance, and in-app purchase (IAP) testing capabilities. It now supports device-like commands and offers dual input methods via keyboard and virtual remote controller, making development and testing more streamlined.

• Improved user experience - Improvements include display boot status and app launch readiness. You can complete device registration directly from the KVD user interface, eliminating offline registration.
• Improved performance - Improvements were made to boot times and provides responsive interactions, delivering a smoother developer experience.
• In-app purchase (IAP) support - IAP support lets you test In-App Purchase flows.
• Device command support - Use Vega Device Adapter (VDA) for device control, which is compatible with all Fire TV device commands.

For more information, follow the official documentation here for using the new simulator for IAP.

New SDK Download & Installation Experience - Tooling

Developers can now enjoy a simplified SDK installation process and improved build performance. We’ve focused on simplifying your first-touch experience with the SDK, with fewer dependencies being installed and faster installation times. We listened to your feedback and created a shorter and more streamlined experience that will suit your needs.

The following components are no longer included or required as part of the installation:

• SDK upgrade through npm commands
• kepler token script
• environment-setup-sdk.sh script
• .knrc file
• conanfile.py file
• find_package directives for Interface packages in CMake
• To download the SDK, visit Install the Kepler SDK.

VDA is no longer in the path by default - Command Line Tools

The way you use Kepler CLI Commands is changing. Rather than Amazon adding multiple commands to your PATH, each Kepler related command is now wrapped by kepler exec (e.g. kepler exec vda <xyz> , kepler exec vpt validate <xyz> ) in order to standardize Kepler commands and minimize what Amazon adds to the PATH by default. Developers can continue to manually add Kepler related commands directly to the PATH if they prefer.
As an example, to list your connected Kepler devices, instead of:

vda devices

you would now run

kepler exec vda devices

Same is true for kepler exec vpt and kepler exec perf.

Note: You can add tools to your PATH for direct invocation to use vda without the kepler exec prefix. Follow the instruction described in the installer prompts.

More Libraries added in the JS Bundle as part of the system - Action Required

As part of our JS Bundle in system initiative, we are introducing more libraries in the system with v0.20 release. As stated above, you will be required to recompile your apps with this release for compatibility with the new default bundling . Please follow the command lines from knowledge base article here as a pre-requisite before rebuilding the application.

Required action:

1. Recompile your apps with this release for compatibility with the new default behavior.

2. Follow these guidelines before rebuilding your app:

3. Make sure you have the latest npm packages for the libraries you use.

4. Change to the folder where your package.json is located.

5. Run these commands:

npm cache clean --force // clears the global npm cache

amzn/react-native-fast-image migration to App bundle

react-native-fast-image has been integrated into the app bundle, enhancing stability, and reducing the memory footprint. This change

• Includes the native module in the npm tarball and app package
• Enables consistent app performance across OS versions without rebuilding
• Reduces memory usage by including FastImage only in apps that use it

Required action:

1. Update to amzn/react-native-fast-image version 3.0.0.
2. Recompile your app.

Availability of New APIs - Features Added

Key highlights include state restoration capabilities for background-terminated apps, enhanced recommendation management with contentImageUri support, and expanded gaming controller functionality for both gaming and non-gaming applications. Security gets a boost with mTLS support, while performance improvements arrive through native URLSearchParams implementation and new Uint8Array methods for efficient binary data handling.

Additional components and props for React Native:

• TextInput (autoComplete, onKeyPress editable, autoCorrect)
• ScrollView (persistentScrollbar)

Headless JS Improvements

We’ve added support for the following libraries after it being requested from developers:

• URLSearchParams library
• I18nManager library

Restoration manager: Apps can now restore UI and app state when relaunched by the user after being terminated by the OS while running in the background. React Native for Kepler now provides hooks to enable apps to save and restore state, ensuring a seamless experience for users.

Recommendation Manager includes contentImageUri field: When apps use the contentImageUri flow, Launcher handles image display correctly based on the view container, while the existing image size restrictions remain in place for the contentImage byte array flow.

Support for gaming controllers: Gaming controllers now support media app navigation through new gamepad listener hooks. Game Controller also functions as a remote for non-gaming app navigation.

Added mTLS Support: React native for Kepler now supports mutual TLS (mTLS) authentication, enabling secure end-to-end encrypted connections. This feature verifies both client and server identities, adding security for data transmission. Configure mTLS settings within Kepler apps using useServerChallengeReceived, a new custom hook that manages server certificate challenges and client certificate settings.

For additional information, please go to this section directly in our release notes.

Developer Tooling

Added developer mode shell reminder: The system notifies you to use developer mode when you run non-root bash shells to optimize the development environment.

New performance tooling: Kepler Studio UI now offers one-click access to performance tools through the sidebar and header navigations. A new performance tooling homepage and streamlined CLI are also available.

New monorepo support: The Kepler extension now supports working with projects in both npm or Yarn monorepo layouts. For details, see configure monorepos.

ESLint Plugin for Coding Best Practices - Developer Tooling

We have now published a new Kepler-specific ESLint plugin which detects coding issues and validates feature implementations, such as the Kepler fully drawn marker. This helps you identify bugs or issues during earlier in the development process.

In Kepler Studio

In the Console

Configure Visual Studio Code Extension PORT - Developer Tooling

The Kepler extension now allows developers to set a custom default port, enabling compatibility with other programs running on the standard 8081 port. This provides flexibility when debugging React Native apps within the Kepler environment.

Port Configuration in Kepler Studio

Improved Memory Reporting with PSS - Developer Tooling

The application now collects and reports (Proportional Set Size) PSS memory usage in addition to the existing Resident Set Size (RSS) reporting. This provides a more comprehensive view of the memory footprint during runtime.

For additional information, please go to this section directly in our release notes.

Reference Apps - Sample Applications

The assets of the following reference apps have been refreshed as we’ve received partner feedback:
KeplerSportApp, KeplerAudioReferenceApp, KeplerVideoApp, KeplerVoiceControlReference.

For additional information, please go to this section directly in our release notes.

Live TV - Live TV Integrations only

New with 0.20 are also the Live TV provider and station logo requirements. If you’re a Live TV partner, reach out to your Amazon contact for integration.

Provider logo requirements:

• Must be monochrome
• Maximum height: 34px
• Maximum width: 25% of overlaying image in horizontal orientation
• Display location: Top-right corner when focused on channel tiles in Search, On Now, Guide, and provider rows

Station logo requirements (channel branding):

• Must be multi-tone images
• Fixed dimensions: 120x68 pixels
• Display locations:
  • Electronic Program Guide (EPG) tombstone
  • Player loading screen
  • Player overlay
• Submission: Through ChannelMetadata.logoUrl during the EPG sync, or through your Amazon contact

What’s changed - Breaking Changes

SDK 0.20, being our mandatory release every app needs to be on prior to device launch, also had to introduce breaking changes in order to get the SDK in a place where we feel confident to release with. Below is a list of breaking changes you can accommodate to, along with sample implementations where applicable.

App Build Output Directory

The CLI’s build directory structure follows a simplified format. Instead of build/<os>-<profile>-<arch>-<build_type> , it now uses build/<arch>-<build_type> .

Autolinking - update your react-native-config.js - Breaking Change

All Turbo Modules, regardless of whether they are standalone or in-app, must have their autolinking configuration in react-native-config.js . We no longer support autolinking configuration in the package.json . This is to align with React Native conventions on other platforms.

Required action:
Move all Turbo Module autolinking configurations to react-native-config.js .

1. For a project with a turbo module, delete the autolink property from your package.json file.

{
  "kepler": {
    "projectType": "turbomodule",
    "targets": [
      "tv"
+   ]
-   ],
-   "autolink": {
-     "samplemodule": {
-       "libraryName": "libsamplemodule.so",
-       "linkDynamic": true,
-       "provider": "application",
-       "components": [],
-       "turbomodules": [
-         "samplemodule"
-       ]
-     }
-   }
  }
}

2. Move the autolink section to the kepler property in react-native.config.js in your project root. Create the file if it does not exist.

module.exports = {
  dependency: {
    platforms: {
      kepler: {
        "autolink": {
          "samplemodule": {
            "libraryName": "libsamplemodule.so",
            "linkDynamic": true,
            "provider": "application",
            "components": [],
            "turbomodules": [
              "samplemodule"
            ]
          }
        }
      }
    }
  }
};

3. If your project is an NPM module (library), update the files property in your package.json file to include the new react-native.config.js file.

Display connection status - Breaking Change

The operating system has improved how it handles TV display connections by implementing automatic media pause functionality when a device becomes inactive. Instead of switching apps between background and foreground states, the system now sends pause events through the Kepler Media Control API (KMC) to stop media playback and mute audio output. This change aligns with Fire OS behavior and creates a more stable experience. While apps using default KMC integration will work automatically with this update, those with custom KMC implementations that ignore pause events will need modifications.

Required action:

• No action needed for apps using the default KMC integration.
• For custom KMC implementations, update your code to handle pause events. For details, see W3C Media integration with Kepler Media Controls. For more background, see Display connection status implementation change in our forum posts.

Runtime privileges enforcement - Breaking Change

In order to continue to be able to use netinfo capabilities, you have to use the requestPrivilege() method before accessing privilege-gated methods starting with v0.20. This affects apps using react-native-netinfo .

Required action:

1. Implement requestPrivilege() method calls.
2. Review v0.19 release notes and security manager documentation.
3. Update apps currently using react-native-netinfo.

Improvements and Known Issues
For a detailed list of improvements and known issues, we’d like to provide you with the detailed sections in the release notes:

• Improvements List (Release Notes)
• Known Issues List (Release Notes)

Headless Service runtime-module for Account Login: - Breaking Change

Starting with SDK v0.20, the use of the headless service runtime module is mandatory for all service components to ensure optimized resource usage. Previously, the KeplerScript runtime module was recommended for use in the Account Login service component up to SDK v0.19. However, continuing to use KeplerScript in SDK v0.20 will now result in a manifest validation error during app build.

Required action:

Change to /com.amazon.kepler.headless.runtime.loader_2@IKeplerScript_2_0 in place of /com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0 in the manifest for the service component. No further code changes are required.

[[components.service]]
id = "com.amazondeveloper.keplervideoapp.interface.provider"
**runtime-module = "/com.amazon.kepler.headless.runtime.loader_2@IKeplerScript_2_0"**
launch-type = "singleton"

Advance Notice - Future SDK Releases

The below are all updates to existing APIs and are of informative matter for the future.

Enhanced KeplerScript TextInput Password Field Behavior - Advance Notice

In future SDK releases the TextInput component’s onSubmitEditing callback behavior will change. The SDK v0.20 callback doesn’t trigger additional keyboard actions when you interact with show or hide password controls in the keyboard user interface.

Security updates for Amazon features - Advance Notice

New security protocols require you to add wants.module and privileges to your app’s manifest when using Amazon Device Messaging, Simple Sign-in, IAP, and Deep Links.

Privacy changes to Kepler Identifiers getFriendlyDeviceName - Advance Notice

In future SDK releases, the getFriendlyDeviceName() method implements privacy controls for accessing user-customized device names. For example, “John’s FTV Stick” contains personal information.

For more information about each of these, please visit our release notes section for advance notice updates.

Links

• Release Notes
• Preview Blog Post

---

The release notes and the preview blog post were used as a base for this blog article.