@amazon-devices/kepler-content-personalization

The Vega Content Personalization API provides functionality that allows an app developer to provide personalized experiences to customers and showcases relevant content.

Get started

Setup

1. Add the following library dependency to the dependencies section of your package.json file.

   Copy code Copied to clipboard.

    "@amazon-devices/kepler-content-personalization": "~1.3.3",
    "@amazon-devices/kepler-epg-provider": "~1.9.124",
    "@amazon-devices/headless-task-manager": "~1.0.0"
   

   • The kepler-content-personalization package provides functionality for sending your content personalization data to the system.
   • The amzn/kepler-epg-provider package would provide the dependencies used for channelDescriptor in PlaybackEvent data model.
   • The headless-task-manager package provides functionality to register your data-pull background service with the system.

2. In your manifest.toml, add the following privileges.

   Copy code Copied to clipboard.

    schema-version = 1
   
    ## Define your package
    [package]
    title = "Vega Video app"
    version = "2.17.0"
    id = "com.amazondeveloper.keplervideoapp"
   
    [components]
    ## Define your app's interactive component (if it doesn't already exist)
    [[components.interactive]]
    id = "com.amazondeveloper.keplervideoapp.main"
    library-name = "com.amazondeveloper.keplervideoapp"
    runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
    categories = ["com.amazon.category.kva"]
    launch-type = "singleton"
   
    ## Define your app's service component which can handle data request.
    [[components.service]]
    id = "com.amazondeveloper.keplervideoapp.content.dataRefresh.provider"
    runtime-module = "/com.amazon.kepler.headless.runtime.loader_2@IKeplerScript_2_0"
    launch-type = "singleton"
    categories = ["com.amazon.category.kepler.media"]
   
    ## Define a process group for each component
    [processes]
    [[processes.group]]
    component-ids = ["com.amazondeveloper.keplervideoapp.main"]
   
    [[processes.group]]
    component-ids = ["com.amazondeveloper.keplervideoapp.content.dataRefresh.provider"]
   
    [wants]
    ## Defines that your app has a dependency on the Content Personalization data service
    [[wants.service]]
    id = "com.amazon.tv.developer.dataservice"
   
    [needs]
    ## Defines the privilege your app needs in order to use the Content Personalization interface to provide data
    [[needs.privilege]]
    id = "com.amazon.tv.content-personalization.privilege.provide-data"
   
    [offers]
    ## Defines the data refresh service component of your app
    [[offers.service]]
    id = "com.amazondeveloper.keplervideoapp.content.dataRefresh.provider"
   
    ## Defines the interactive component of your app
    [[offers.interaction]]
    id = "com.amazondeveloper.keplervideoapp.main"
   
    ## Add extras to declare support for Content Personalization
    [[extras]]
    key = "interface.provider"
    ## If you're utilizing account login or content launcher interface,
    ## replace component-id with appropriate service component. Follow Account Login Integration Guide
    component-id = "com.amazondeveloper.keplervideoapp.content.dataRefresh.provider"
   
    ## Defines support for the Content Personalization interface and the attributes
    [[extras.value.application.interface]]
    interface_name = "com.amazon.kepler.media.IContentPersonalizationServer"
    attribute_options = ["SupportedCustomerLists", "DataRefreshComponentId"]
   
    [extras.value.application.interface.static_values]
    SupportedCustomerLists = ["Watchlist"]
    DataRefreshComponentId = "com.amazondeveloper.keplervideoapp.content.dataRefresh.provider"
   

   Warning: Each interface configuration must be kept separate. Do not combine or mix attributes between different interfaces in the manifest file.

Related topics

Get Started with Vega Content Personalization

API Reference

Classes

• BaseError
• ContentEntitlementBuilder — Builder to create a ContentEntitlement object.
• ContentIdBuilder — Builder to create a ContentId object.
• ContentInteractionBuilder — Builder to create a ContentInteraction object.
• CustomerListEntryBuilder — Builder to create a CustomerListEntry object.
• InvalidArgumentError — Error thrown when invalid argument is passed to method.
• PlaybackEventBuilder — Builder to create a PlaybackEvent object.
• ProfileIdBuilder — Builder to create a ProfileId object.

Interfaces

• IContentEntitlement — Interface representing a customer's individual content entitlement. Created using ContentEntitlementBuilder.
• IContentEntitlementsHandler — Interface that content provider applications implement to handle commands from Amazon's content personalization service to fetch content entitlement data.
• IContentEntitlementsProvider — Used to provide responses to commands requesting content entitlement data.
• IContentId — Interface representing a content ID. Create using ContentIdBuilder.
• IContentInteraction — Interface representing a customer's interaction with content. Create using ContentInteractionBuilder.
• IContentPersonalizationServer — Interface for Content Personalization Server
• ICustomerListEntriesHandler — Interface that content provider applications implement to handle commands from Amazon's content personalization service to fetch customer managed list data.
• ICustomerListEntriesProvider — Used to provide responses to commands requesting customer managed list data.
• ICustomerListEntry — Interface representing an entry in a customer managed list. Create using CustomerListEntryBuilder.
• IPlaybackEvent — Interface representing a customers playback state at a moment in time. Create using PlaybackEventBuilder.
• IPlaybackEventsHandler — Interface that content provider applications implement to handle commands from Amazon's content personalization service to fetch playback event data.
• IPlaybackEventsProvider — Used to provide responses to commands requesting playback event data.
• IProfileId — Interface representing a profile ID within a namespace.

Enumerations

• ContentIdNamespaces — Enum representing options for ContentId namespaces.
• ContentInteractionType — Enum representing the type of content interaction.
• CustomerListType — Enum representing the type of list the customer manages.
• EntitlementType — Enum representing the type of content entitlement.
• PlaybackState — Enum representing the state of content playback.
• ProfileIdNamespaces — Enum representing options for ProfileId namespaces.

---

Last updated: Jul 22, 2026