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
Earlier versions of the Vega SDK shipped experimental APIs that weren’t final, and deprecated APIs that have stable successors. Vega SDK 2.0 is generally available, and it removes both in favor of stable APIs. Apps you already built with an earlier SDK keep working, because Vega OS still implements these APIs. The change hits when you build with Vega SDK 2.0: code that uses them doesn’t compile. The exception is UI toolkit graphics, where an app you already built can fail on Vega 2.0 devices. This guide covers the experimental and deprecated interface definition language (IDL) APIs that have stable replacements in Vega SDK 2.0. It also covers the manifest change every app makes to target 2.0. The per-API sections are for native code. If your app is JavaScript and TypeScript only, with no native module of your own, only the manifest change applies to you. Each section describes what changed and what to do about it. Where a stable replacement isn’t established yet, the section marks it Unresolved. If your code uses one of those APIs, ask your Amazon contact. For the full contract of any stable API, read its IDL. Each section names its IDL file and links to its package in the API reference, which documents every interface, method, and type in far more detail than this guide.

​
Which of these apply to you

To find the experimental code this guide affects, search your native sources for experimental, case-insensitively. Deprecated APIs don’t carry that word, so search for their names too. The following table maps what you find to the section that covers it.

​
Target Vega 2.0 in the app manifest

Update your app manifest to target 2.0. In manifest.toml, set [os.version] min and target to 2.0, and update the [[needs.module]] entry from /com.amazon.vega.os@IVega_1_2 to /com.amazon.vega.os@IVega_2_0. To set the minimum and target versions from the command line, run the following command in your project directory:
Then check that the [[needs.module]] entry in manifest.toml reads /com.amazon.vega.os@IVega_2_0. A minimum of 2.0 keeps your updated app off older devices, where some of the APIs in this guide behave differently or don’t exist.

​
Remove local copies of SDK IDLs

The Vega SDK 2.0 now installs a full set of supported IDLs. Before SDK 2.0, some IDLs went to partners out of band. A local copy of an IDL takes precedence over the copy the SDK includes, so your app builds against the local one without a warning. Look for .idl files inside your project under a path that mirrors an SDK namespace, for example apmf/iface/com/amazon/kepler/. Delete any that SDK 2.0 provides, and build against the SDK provided IDLs.

​
Suggested order

Take the sections in the following order, which starts with the renames and puts messaging before the two changes that depend on it: The following table shows the estimated effort for each section.

​
Lifecycle management API

The stable API com.amazon.kepler.application replaces com.amazon.kepler.experimental_mr33.app. Full definitions are in application.idl. The stable API retains IInteractiveComponent, IServiceComponent, ITaskComponent, IComponentFactory, IMemoryWarningHandler, IMemoryWarningInfo, and MemoryLevel.

​
What changed

Differences beyond the namespace:
  • IComponentInstance moved to com.amazon.kepler.runtime.
  • IMessage is now stable messaging. onStart and onNewLaunch take com.amazon.kepler.messaging.IMessage.
  • ITaskComponent2 folded into ITaskComponent, where onNewLaunch is now a base method.
  • onSaveState(instance) is new on IInteractiveComponent. It fires after the component goes to the background, and gives you a final chance to save state through IRestorationManager.
  • onReconfigure and ReconfigureReason are removed.

​
What to do

  • Update the imports and the namespace to com.amazon.kepler.application.
  • Take IComponentInstance from com.amazon.kepler.runtime and IMessage from com.amazon.kepler.messaging. Migrate all three together.
  • If you implemented ITaskComponent2, collapse it onto ITaskComponent.
  • Implement onSaveState and save UI state through IRestorationManager. It runs on the main thread, so finish any cross-thread collection before you return, and don’t throw, because an exception there terminates the app.

​
Unresolved

Reacting to locale, timezone, and day and night changes. onReconfigure notified a component that the system had been reconfigured. Check the runtime and config APIs for a replacement, and ask your Amazon contact before you migrate.

​
Messaging API

The stable API com.amazon.kepler.messaging replaces com.amazon.kepler.experimental_mr33.messaging. This is a redesign rather than a rename, so expect many call sites to change. Full definitions are in messaging.idl.

​
What changed

IMessageChannel and IMessageChannel2 are removed. The entry-point interface IMessagingModule replaces IKeplerMessagingModule:
  • Sending messages moves from IMessageChannel to IMessagingModule: send(IMessage* message, IMessageListener? listener). The listener is optional. Pass nullptr and no callbacks fire for delivery, response, or error.
  • Registering filters moves from IMessageChannel to IMessagingModule: registerMessageFilter(IMessageFilter*[] filters, IMessageListener* listener) returns an IMessageFilterSubscription. To detach the listener and stop delivery, call unsubscribe(), which the subscription inherits from ISubscription. To remove specific filters and keep the listener attached, call unsubscribeFilters(filters).
IMessage accessors change name, and one changes type. The following table shows the renamed accessors. You no longer call QueryInterface on the result of getAttachmentBytes(). Deserialize the bytes with GetDoFromArray<T> instead. On the sending side, IMessageBuilder.attachment() now takes an IDataObject* instead of an IStandard*. IMessageListener2 folded into IMessageListener, where onMessageDelivered() is now a base method. priorityHint(MessagePriorityHint::IMMEDIATE) on IMessagePropertiesBuilder is replaced by markUrgent(). Also new. The access control methods on IMessagingModule: canSendUri, canSendUriForCredential, and canReceiveUriForCredential. They expand what IMessageChannel2.canSendUri did.

​
What to do

  • Delete channel creation. makeMessageChannel followed by channel->send(...) becomes module->send(message, listener).
  • Replace channel->registerMessageFilter(...) with module->registerMessageFilter(filters, listener), and keep the returned subscription. Dropping your references doesn’t unsubscribe.
  • Rename the IMessage reads, and rewrite attachment extraction to getAttachmentBytes() with GetDoFromArray<T>.
  • Pass an IDataObject to IMessageBuilder.attachment().
  • Implement onMessageDelivered() in every IMessageListener. If you implemented IMessageListener2, collapse it onto IMessageListener.
  • Replace priorityHint(MessagePriorityHint::IMMEDIATE) with markUrgent().
  • Test the send, receive, response, and filter paths.

​
Input method API

The stable API com.amazon.kepler.intl.input_method replaces com.amazon.kepler.experimental.intl.input_method. This is a promotion to stable with no redesign. Full definitions are in input_method.idl.

​
What changed

The [Experimental] package annotation and the com.amazon.apmf.Experimental import are removed. The namespace drops experimental., and the package version moves from 1.0 to 2.0.

​
What to do

Update the import path and the namespace. Recompile and confirm.

​
Media control

The stable API com.amazon.kepler.media.control replaces com.amazon.kepler.media.experimental_control_2024_02. The interfaces are unchanged. After you update the namespace and includes your existing calls keep working. Full definitions are in control.idl.

​
What changed

The following table shows the extension types that Vega SDK 2.0 adds.

​
What to do

Update the namespace and includes. The following extension types are optional. Adopt the matching one to add a capability:
  • Ratings: prefer MediaSessionState2.ratingState when it’s present. It’s null when the provider doesn’t support structured ratings for the session, so keep the MediaInfo.currentRating fallback.
  • Dark theme: supply darkLogo on MediaProviderInfo2.
  • Collections: populate collectionName when your content has a playlist or mix name.
  • Cross-system correlation: to match a session across process or device boundaries, use MediaSessionId2.token.

​
Graphics

com.amazon.kepler.graphics is already stable, but 2.0 replaces the IObjectFactory entry point, which had unstable dependencies, with IGraphicsModule. Native apps use graphics, so check for it even though a search for experimental won’t find it. Full definitions are in graphics.idl.

​
What changed

  • You acquire graphics through IGraphicsModule, and the component path drops the interface suffix.
  • createDisplayController(instance, nullptr) becomes createDisplayControllerForApp(instance, nullptr), where instance is a com.amazon.kepler.runtime.IComponentInstance.
  • createMediaSurface, createGpuDeviceUsingOpenGlesApi, and createWindow keep their names, now called on IGraphicsModule.

​
What to do

  • Include graphics/IGraphicsModule.h in place of graphics/IObjectFactory.h.
  • Change the acquisition from getComponent("/com.amazon.kepler.graphics.IObjectFactory") queried to IObjectFactory, over to getComponent("/com.amazon.kepler.graphics") queried to IGraphicsModule.
  • Rename createDisplayController(instance, nullptr) to createDisplayControllerForApp(instance, nullptr).

​
Tasks API

The com.amazon.kepler.tasks package is already stable, but the experimental flow inside it is removed in 2.0. Full definitions are in tasks.idl.

​
What changed

ITaskInput_Experimental_MR33 and ITaskRequestBuilder_Experimental_MR33 are removed. Both tied you to experimental messaging: getMessageTrigger() returned com.amazon.kepler.experimental_mr33.messaging.IMessage, and requireMessage() took an experimental IMessageFilter. Code that uses them won’t compile against 2.0. Vega SDK 2.0 adds the stable path:
  • TaskExecutionInfo, a struct with uuid and name that identifies one task execution.
  • ITaskManager2, with tryGetMessageTrigger(TaskExecutionInfo*) returning stable IMessage?, and submitResult(TaskExecutionInfo*, ITaskResult*).
The trigger message and the result no longer flow through a task-input object. The trigger arrives as your onStart message, and you submit the result through ITaskManager2.

​
What to do

  • Read the TaskExecutionInfo from the launch message’s attachment: GetDoFromArray<TaskExecutionInfo>(message->getAttachmentBytes()).
  • Get an ITaskManager2 from the tasks module’s makeTaskManager(), and submit your result with submitResult(taskExecutionInfo, result).
  • Complete a task that can’t submit a result by calling executionCompleted() on the instance’s IComponentInstance2, not through IAppLifecycleControl.
  • Migrate Messaging first, and finish both migrations together.
  • Move your ITaskComponent implementation to stable com.amazon.kepler.application at the same time. Its onStart and onNewLaunch take stable IMessage and the runtime IComponentInstance.

​
Lifecycle control

The stable APIs com.amazon.kepler.runtime and com.amazon.kepler.app_lifecycle replace com.amazon.kepler.experimental_mr33.app_lifecycle_control. Instance-scoped control moves to runtime, and termination data stays in app_lifecycle. Full definitions are in runtime.idl and app_lifecycle.idl.

​
What changed

The call pattern inverts. Previously you held a separate control object and passed it the instance. Now you call the instance itself from inside your app process, through these runtime interfaces:
  • IComponentInstance gains getComponent().
  • IComponentInstance2 has executionCompleted(), which takes no argument.
  • IInteractiveComponentInstance, which extends IComponentInstance2, has requestBack(), makeInstanceConfigBuilder(), and configure().
  • IInteractiveComponentConfiguration and IInteractiveComponentConfigurationBuilder are new. The builder offers transientLifespan(), shortLifespan(), longLifespan(), permanentLifespan(), timeout(), disableTimeout(), and build().
IAppLifecycleControl2.tryGetLastTerminationData() still returns ITerminationInfo?, and TerminationReason stays with it. If you use last-termination information, that code doesn’t move. IAppLifecycleControl.executionCompleted(instance) in app_lifecycle is marked Deprecated (2026-01), and so is the same method on IAppLifecycleControl2. That’s the old call pattern, and the deprecation marks the move to the instance-scoped form.

​
What to do

  • Replace control->executionCompleted(instance) with instance->executionCompleted(). To get IComponentInstance2, call QueryInterface on the instance you were given.
  • For back navigation and configuration on interactive components, call QueryInterface for IInteractiveComponentInstance, then call requestBack().
  • Set lifespan and timeout through makeInstanceConfigBuilder() and configure(). Lifespan controls which instance a backstack walk can transition to.

​
DHCP

The stable API com.amazon.kepler.net.dhcp replaces com.amazon.kepler.experimental_vr10.net.dhcp. Full definitions are in dhcp.idl.

​
What changed

IDhcpModule, IDhcpServer, IDhcpSettings, and IDhcpSettingsBuilder don’t change.

​
What to do

Update the namespace and the import. Recompile and confirm.

​
Content personalization

IContentPersonalizationServerComponent2 and IContentPersonalizationServer2 replace the deprecated IContentPersonalizationServerComponent and IContentPersonalizationServer in com.amazon.kepler.tv.personalization. The deprecated interfaces aren’t in Vega SDK 2.0. Full definitions are in personalization.idl.

​
What changed

  • getOrMakeServer() becomes getOrMakeServer2(), which returns IContentPersonalizationServer2.
  • Each handler setter now takes the component instance it serves, a com.amazon.kepler.runtime.IComponentInstance. The following table shows the renamed setters.
  • makeContentEntitlementsProvider(), makeCustomerListEntriesProvider(), and makePlaybackEventsProvider() are removed from the server component. Your handlers receive a provider as their callback argument.
  • The report* methods and the make*Builder methods don’t change.

​
What to do

  • Replace the deprecated types everywhere you use them, including Ptr<> members, using declarations, and mock and helper signatures.
  • Include IContentPersonalizationServer2.h and IContentPersonalizationServerComponent2.h from apmf/iface/com/amazon/kepler/tv/personalization/ in place of the unversioned headers. Add apmf/iface/com/amazon/kepler/runtime/IComponentInstance.h.
  • Call getOrMakeServer2().
  • Get the runtime IComponentInstance from the instance your component receives, by calling TryQueryInterface<com::amazon::kepler::runtime::IComponentInstance>() on it. Pass it to each ...ForComponent setter.
  • Stop calling the make*Provider() methods. Use the provider your handler receives.
  • If you can’t get a component instance or resolve the server component, log it and continue rather than failing initialization.

​
Subscription entitlement

ISubscriptionEntitlementServerComponent2 and ISubscriptionEntitlementServer2 replace the deprecated ISubscriptionEntitlementServerComponent and ISubscriptionEntitlementServer in com.amazon.kepler.tv.subscription_entitlement. The deprecated interfaces aren’t in Vega SDK 2.0. Full definitions are in subscription_entitlement.idl.

​
What changed

  • getOrMakeServer() becomes getOrMakeServer2(), which returns ISubscriptionEntitlementServer2.
  • setSubscriptionEntitlementsHandler(handler) becomes setSubscriptionEntitlementsHandlerForComponent(handler, instance), where instance is a com.amazon.kepler.runtime.IComponentInstance.
  • makeSubscriptionEntitlementsProvider() is removed from the server component. Your handler’s getAllSubscriptionEntitlements receives a provider.
  • setSubscriptions(subscriptions) is new. It replaces the whole subscription list.
  • reportNewSubscription and reportRemovedSubscription still exist on ISubscriptionEntitlementServer2, but they’re deprecated in favor of setSubscriptions.

​
What to do

  • Replace the deprecated types and includes with the ...2 versions.
  • Call getOrMakeServer2(), and register your handler with setSubscriptionEntitlementsHandlerForComponent. Get the runtime IComponentInstance the same way as for Content personalization.
  • Call setSubscriptionEntitlementsHandlerForComponent before reportRefreshedSubscriptions.
  • Replace reportNewSubscription and reportRemovedSubscription with setSubscriptions, passing the full current list.
  • Stop calling makeSubscriptionEntitlementsProvider(). Use the provider your handler receives.

​
Channel server

The stable API com.amazon.kepler.tv.kepler_channel_server2 replaces the deprecated com.amazon.kepler.tv.kepler_channel_server. It covers IChannelServerComponentAsync, IChannelServerAsync, IChannelHandlerAsync, and IChangeChannelPromise. Full definitions are in kepler_channel_server2.idl.

​
What changed

  • The component instance moves from getting the server to setting the handler. getOrMakeServer(component) becomes getOrMakeServer(), and setHandler(handler) becomes setHandlerForComponent(handler, component).
  • IChannelHandlerAsync and IChangeChannelPromise keep the same methods in the new namespace.

​
What to do

  • Update the namespace to kepler_channel_server2 and the includes to apmf/iface/com/amazon/kepler/tv/kepler_channel_server2/.
  • Call getOrMakeServer() with no argument, then setHandlerForComponent(handler, component) with the component instance you were passing before.
  • Recompile your handler and promise code against the new namespace.

​
EPG program lineup

IProgramLineupProvider2 replaces the deprecated IProgramLineupProvider in com.amazon.kepler.tv.epg_provider. Full definitions are in epg_provider.idl.

​
What changed

  • You get the provider from IEpgProviderFactory2.makeProgramLineupProvider2() instead of IEpgProviderFactory.makeProgramLineupProvider().
  • upsert(programs) returns an array of IUpsertProgramFailure instead of nothing. It skips programs that fail and keeps inserting the rest.
  • clearAllPrograms() and commit(version) don’t change.

​
What to do

  • Query the factory for IEpgProviderFactory2 and call makeProgramLineupProvider2().
  • Check the failures upsert returns, and handle or log each one.

​
UCC TextChunk

The data object TextChunk2 replaces the deprecated struct TextChunk in com.amazon.kepler.ucc.v1_0.common. Full definitions are in common.idl.

​
What changed

The following table shows the field changes. The methods that take text move to versioned interfaces:

​
What to do

  • Build TextChunk2 objects in place of TextChunk structs.
  • Convert fontSize from pixels to points, and pass language as a Locale.
  • Set interpretationType on every chunk.
  • Call text2, addPane2, and addCollectionInfo2 on IDescribeElement2.

​
Unresolved

How to construct a TextChunk2. Check common.idl, and ask your Amazon contact.

​
UI toolkit graphics

com.amazon.kepler.uitoolkit.graphics.IGraphicsModule5 keeps its name in Vega SDK 2.0, but its definition changed. This is a different interface from the com.amazon.kepler.graphics.IGraphicsModule in Graphics.

​
What changed

  • In SDK 0.24, IGraphicsModule5 extends IGraphicsModule4 and adds getShareableSurfaceRegistry(). In 2.0, it extends IGraphicsModule4 and adds makePathMeasure(IPath* path, bool forceClosed) instead.
  • The two versions are binary-incompatible. Code built against 0.24 that queries IGraphicsModule5 doesn’t compile against 2.0. Code built against 2.0 that queries IGraphicsModule5 works only on Vega 2.0 devices or later.
  • An app you already built with 0.24 that queries IGraphicsModule5 can fail at runtime on Vega 2.0 devices, with an IDL hash break exception. To keep it working, rebuild and resubmit it.
  • IShareableSurfaceRegistry, IShareableSurfaceObserver, and ShareableSurfaceHandle are removed, with no public replacement.

​
What to do

  • If you query IGraphicsModule5 only to call methods it inherits from IGraphicsModule4, query IGraphicsModule4 instead. You don’t need to change your minimum OS version.
  • If you call makePathMeasure, query IGraphicsModule5 and set your minimum OS version to 2.0, as described in Target Vega 2.0 in the app manifest.

​
Unresolved

ShareableSurface. If your code calls getShareableSurfaceRegistry(), ask your Amazon contact before you migrate.

​
Deprecated methods

These methods are deprecated, but their interfaces aren’t, so migrate the call and keep the interface. The IDL comment for digestAlgorithm names crypto3.IHmacContextBuilder2. That namespace isn’t in the SDK. Use IHmacContextBuilder2 in com.amazon.kepler.crypto. For keystore MAC keys, build the key with IKeystore2.makeMacKeyBuilder() instead of makeSymmetricKeyBuilder(). IKeystoreMacKeyBuilder inherits macAlgorithm from com.amazon.kepler.crypto.IHmacKeyBuilder, so you won’t find it on the keystore interface itself. The algorithm parameter changes type from IDigestAlgorithm to IMessageAuthenticationCode.
Last modified on November 2, 2026