Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases

Console

as

Get Started
Design and Develop
Publish
Reference
Support
Native
Skip to main content
The Vega Virtual Device (VVD) lets you build, run, and debug your Vega app without a physical device. It works well for fast iteration on app logic, UI, navigation, and most native APIs. Some features need a Fire TV device. This page lists what behaves differently on the VVD in Vega SDK 2.0. It also covers what your app sees when it reaches a limit and how to handle it. The content reflects testing with Vega OS 2.0 on the VVD and on a Fire TV device.

​
Supported native APIs

The native components in the following table work on both the VVD and a Fire TV device. Supported means your app can bind to the component and a basic call succeeds. It doesn’t mean that every feature behind the component was tested. The table lists only components whose interfaces ship in Vega SDK 2.0. The Package or API column names the @amazon-devices package that uses the component, where there is one. It also names the Vega Native API reference package and the interface you get from the component.

​
Content Launcher and Account Login

Your app can register its Content Launcher and Account Login handlers on the VVD. The system features that send requests to those handlers aren’t available on the VVD. These features include the Fire TV Home screen, search, and Alexa voice requests. To test Content Launcher and Account Login integration, use a Fire TV device. For details, see Content Launcher and Account Login Testing.

​
Declare the backing service

The buffer queue component and the EPG provider work only after your manifest declares their backing service. Without the declaration, calls fail on both the VVD and a Fire TV device.
  • Buffer queue component: declare the media buffer service in [[wants.service]].
  • EPG provider: declare the services com.amazon.tv.developer.dataservice.service and com.amazon.alexa.datastore.service in [[wants.service]]. Declare the privilege com.amazon.kepler.tv.privilege.data_provider in [[needs.privilege]]. For details, see Declare EPG Sync Task.

​
Components not available on the VVD

The components in the following table aren’t included in the VVD in this release. They’re available on a Fire TV device. Login with Amazon (LWA), the Fire TV launcher (the Home screen app), and other Fire TV middleware also aren’t supported on the VVD. Test integrations with them on a Fire TV device. Some system services that Amazon libraries use internally are also missing: Alexa voice services (directives, dictation, captions, and the visual indicator), native ad measurement, privacy consent, and device telemetry. Your app doesn’t call these services directly, but a library or package it depends on might. If it does, your app can behave as described in What your app sees.

​
What your app sees

The result depends on how your manifest declares the component. If your manifest declares the component in [needs], installation fails. Both vega device install-app and vega run-app report the missing module, as in the following example.
If your manifest declares the component in [wants], installation succeeds and vega run-app reports that the app launched. After launch, the result depends on your app:
  • A native app that looks up the component and checks the result gets com.amazon.apmf.NoSuchComponentError with the message could not find component "<component-id>".
  • A native app that uses the result without checking it stops with SIGABRT. The crash report doesn’t name the missing component.
  • A React Native app that calls Simple Sign-In through @amazon-devices/simplesignin stops inside the native module. A JavaScript try/catch block doesn’t catch this failure, and the app receives no JavaScript error.
If your app reaches one of these components through a library and your manifest doesn’t declare it, you get no install message.

​
How to handle missing components

  • Test features that use these components on a Fire TV device.
  • To make sure your app still installs on the VVD, declare optional features in [wants] instead of [needs].
  • In native code, check that a component lookup succeeded before you use the result, and handle NoSuchComponentError.
  • While you test on the VVD, don’t call Simple Sign-In. For example, put the call behind a flag in your test builds.
  • Test sign-in flows on a Fire TV device.
  • In native code, use the system information component (/com.amazon.kepler.system.info, interface ISystemInfoModule) to check whether the device is an emulator. You can then skip calls to unavailable components on the VVD.

​
DRM and protected playback

Clear (unencrypted) video playback works on the VVD. For protected playback, the VVD supports Widevine L3 (software robustness) on Mac M-series machines. On other host machines, DRM-protected playback isn’t available. Protected playback has the following limits:
  • Widevine L3 works, Widevine L1 doesn’t. The VVD includes only a software Widevine module (Widevine L3), so request software robustness when your app runs on the VVD. Widevine L1, hardware-secure robustness levels, and PlayReady aren’t available.
  • Secure robustness requests fail at media key creation. Your app can request SECURE_DECRYPT or HW_SECURE_ALL robustness through the native W3C media API or through EME. The key system access request succeeds, but creating the media keys fails with the following error.
    If your app doesn’t handle this failure, it can crash later, for example when it moves to the background. In testing, a React Native player app that requested HW_SECURE_ALL crashed in the foreground.

​
How to handle DRM limits

  • Handle failures from requestMediaKeySystemAccess and from media key creation.
  • Don’t assume that media keys exist after key system access succeeds.
  • If media key creation fails, show an error or fall back to content your app can play. Don’t continue with a missing DRM session.
  • On the VVD, test Widevine-encrypted playback at software robustness (Widevine L3). Use clear content for the rest of your player UI and playback logic.
  • To test Widevine L1 (hardware-secure) or PlayReady playback, use a Fire TV device. For details, see Media Player playing DRM content.

​
Native libraries in task and service components

On the VVD, task and service components can start in a minimal process that doesn’t preload the graphics libraries. In testing, this behavior didn’t affect interactive components. A task or service component can load a shared library that calls OpenGL ES functions but doesn’t link the GL library itself. In that case, the library fails to load and the component doesn’t start. The device log shows an error like the following one.
The undefined symbol can be any gl* function your library calls. If your interactive component waits on the failed component, your app can stop responding. One shared library can serve both your interactive component and your task or service components. If any of that code calls GL functions, link the GL libraries explicitly. The following example shows how to link GLESv2 in CMake.
If your library calls egl* functions, link EGL the same way. Explicit linking makes the dependency visible to the loader on any device. Your library then doesn’t depend on which libraries the system preloads.

​
Developer tools on the VVD

The following developer tools behave differently on the VVD:
  • Warm start key performance indicator (KPI): the KPI Visualizer’s warm start measurement can report no value on the VVD. The tool’s setup step can’t switch to the Home screen on the VVD. Measure warm start on a Fire TV device. For details, see Measure App KPIs.
  • Launch results: vega run-app can report a successful launch for an app that stops right after it starts. For example, a missing component in [wants] can cause this result. For details, see What your app sees.
Last modified on November 3, 2026