Get Started with Vega Content Personalization

Here’s what you need to know to integrate Vega Content Personalization into your app for Fire TV. If you want to review some of the types of data used for this integration, see the Data Type Reference. If the data isn’t accessible or needs to be transformed, this integration may take longer. Confirm your data is stored in the requested format using the documentation below.

Prerequisites

Access to the source code of your Fire TV app.
A Fire TV device that supports this integration. Check with your Amazon contact for a list of device types currently supported.
Your app must participate in the Catalog Ingestion process, so Fire TV recognizes the content IDs.
Your app must complete the Content Launcher integration.

Integration steps

Step 1. Include the package dependencies in your app

Add the kepler-content-personalization, headless-task-manager, and amzn/kepler-epg-provider dependencies in your package.json file.

"dependencies": {
    "@amazon-devices/react-native-kepler": "~2.0.0",
    "react": "18.2.0",
    "react-native": "0.72.0",
    "@amazon-devices/kepler-content-personalization": "~1.2.0",
    "@amazon-devices/kepler-epg-provider": "~1.0.0",
    "@amazon-devices/headless-task-manager": "~1.0.0"
  }

The kepler-content-personalization package provides APIs 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 APIs to register your data-pull background service with the system.

Step 2. Update your manifest file

Update your manifest.toml file to include Content Personalization support. Here’s an example for a sample app:

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"

Here’s an example of the correct way to define multiple interfaces:

[extras.value.application]
[[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"

[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.IContentLauncherServer"
override_command_component = { LaunchContent = "com.amazondeveloper.keplervideoapp.main" }
attribute_options = ["partner-id"]

[extras.value.application.interface.static_values]
partner-id = "<Your partner id>"

Here’s an incorrect way to define interfaces. Don’t do it this way.

[extras.value.application]
[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.IContentPersonalizationServer"
attribute_options = ["SupportedCustomerLists", "DataRefreshComponentId"]

[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.IContentLauncherServer"
override_command_component = { LaunchContent = "com.amazondeveloper.keplervideoapp.main" }
attribute_options = ["partner-id"]

[extras.value.application.interface.static_values]
partner-id = "<Your partner id>"
SupportedCustomerLists = ["Watchlist"]
DataRefreshComponentId = "com.amazondeveloper.keplervideoapp.content.dataRefresh.provider"

Step 3. Make a sample API call

Begin with a sample/mock event generated at the app launch. To construct the event and send it, use the following code:

// Example playback event generated when user starts watching content

const playbackEvent: IPlaybackEvent = new PlaybackEventBuilder()
    .playbackPositionMs(0)
    .playbackState(PlaybackState.PLAYING)
    .durationMs(2000)
    .eventTimestamp(new Date())
    .contentId(
    new ContentIdBuilder()
        .id('content_CDF_ID')
        .idNamespace(ContentIdNamespaces.NAMESPACE_CDF_ID)
        .build(),
    )
    .profileId(
    new ProfileIdBuilder()
        .id('myProfileId')
        .idNamespace(ProfileIdNamespaces.NAMESPACE_APP_INTERNAL)
        .build(),
    )
    .buildActiveEvent();

// Send the event
ContentPersonalizationServer.reportNewPlaybackEvent(playbackEvent);

Step 4. Validate the integration

Trigger the sample event code you constructed to run inside your app. After you run the code successfully, view the logs to validate the SDK has been linked to your app and is processing the message. You can validate the steps by searching your app logs:

journalctl --follow |grep -Ei 'kepler.tv.personalization'

The log message you receive for the event shown in Step 3 should contain at least one of the following logs:

Dec 15 00:53:15.705114 carat-3fc19fb5ae526e4d local0.info keplerscript-ru[22814]: 1483317178 INFO kepler.tv.personalization.ancp.turbomodule:reportNewPlaybackEvent called
Dec 15 00:53:15.711945 carat-3fc19fb5ae526e4d local0.info keplerscript-ru[22814]: 1483317178 INFO kepler.tv.personalization:PlaybackEventBuilder buildActiveEvent() called
Dec 15 00:53:15.711990 carat-3fc19fb5ae526e4d local0.info keplerscript-ru[22814]: 1483317178 INFO kepler.tv.personalization:reportNewPlaybackEvent call received

Step 5. Make API calls as part of in-app functionality

For each data type, review the data type’s “When to Send” section to understand where in your code to make calls to Vega Content Personalization. Find the relevant parts of your code that run when customers take each action and add an API call. Each data type has different triggers.

For Watch Activity, see Watch Activity: When to Send.
For Watchlist, see Watchlist: When to Send.

For example, when a customer adds an item to their watchlist, you must call the reportNewCustomerListEntry API with the relevant information. First, locate the code in your app that adds items to the watchlist, and then make the API call as part of your logic.

Step 6. Implement your data pull service for background or off-device data

To allow Amazon to pull data from your app, implement the service as described below. The service contains everything needed to setup and connect, only requiring you to implement the functions to send data to a receiver object. This object allows you to share data in chunks, as needed. This prevents loading large lists into memory.

Create a service.js file with the same path where package.json is located with the following content. This tells the system about the entry points for your content.dataRefresh.provider service.

import { HeadlessEntryPointRegistry } from '@amazon-devices/headless-task-manager';

import {
onStartService,
onStopService,
} from './src/headless/HeadlessService';

HeadlessEntryPointRegistry.registerHeadlessEntryPoint2(
'com.amazondeveloper.keplervideoapp.content.dataRefresh.provider::onStartService',
() => onStartService,
);

HeadlessEntryPointRegistry.registerHeadlessEntryPoint2(
'com.amazondeveloper.keplervideoapp.content.dataRefresh.provider::onStopService',
() => onStopService,
);

Create your Headless Service Interface file under src/headless/HeadlessServiceInterface.ts with the following content:

import {
IComponentInstance,
} from "@amazon-devices/react-native-kepler";

export interface HeadlessServiceInterface {
/**
 * This function is called when native service onStart is called.
 * @param {IComponentInstance} componentInstance - The headless component instance.
 */
onStart(componentInstance: IComponentInstance): Promise<void>;

/**
 * This function is called when native service onStop is called.
 * @param {IComponentInstance} componentInstance - The headless component instance.
 */
onStop(componentInstance: IComponentInstance): Promise<void>;
}

Create your data pull service under src/headless/HeadlessService.ts with the following content:

import { ContentPersonalizationServer, CustomerListType, ICustomerListEntriesHandler, ICustomerListEntriesProvider, IPlaybackEventsHandler, IPlaybackEventsProvider } from "@amazon-devices/kepler-content-personalization";
import { HeadlessServiceInterface } from "./HeadlessInterface";
import { IComponentInstance } from "@amazon-devices/react-native-kepler";

/*********** Content Personalization Handlers *************/
const customerListEntriesHandler: ICustomerListEntriesHandler = {
   getAllCustomerListEntries: (
      listType: CustomerListType,
      customerListEntriesProvider: ICustomerListEntriesProvider,
   ) => {
      customerListEntriesProvider.addCustomerListChunk(listType, <ADD LIST ENTRIES>);
      customerListEntriesProvider.commit();
   },
};

const playbackEventsHandler: IPlaybackEventsHandler = {
   getPlaybackEventsSince: (
      sinceTimestamp: Date,
      playbackEventsProvider: IPlaybackEventsProvider,
   ) => {
      playbackEventsProvider.addPlaybackEventChunk(<ADD PLAYBACK EVENTS>);
      playbackEventsProvider.commit();
   },
};

/*********** Assign the Content Personalization Handlers *************/
class HeadlessService implements HeadlessServiceInterface {
   onStart(componentInstance: IComponentInstance): Promise<void> {
      ContentPersonalizationServer.setCustomerListEntriesHandlerForComponent(
            customerListEntriesHandler, componentInstance
      );
      ContentPersonalizationServer.setPlaybackEventsHandlerForComponent(
            playbackEventsHandler, componentInstance
      );
      return Promise.resolve();
   }

   onStop(componentInstance: IComponentInstance): Promise<void> {
      return Promise.resolve();
   }
}

const HeadlessServiceInstance = new HeadlessService() as HeadlessServiceInterface;

export const onStartService = (componentInstance: IComponentInstance): Promise<void> => {
   return HeadlessServiceInstance.onStart(componentInstance);
};

export const onStopService = (componentInstance: IComponentInstance): Promise<void> => {
   return HeadlessServiceInstance.onStop(componentInstance);
};

Make changes to your catalog integration when directed by your Amazon contact

To make use of the activity data, Fire TV needs the following data from your existing Fire TV catalog integration. Fire TV’s public catalog integration documentation will be updated to include these elements in the future, but here is a preview of what’s needed concerning the Vega Content Personalization integration. Your Amazon contact will inform you of when to begin these catalog changes.

International - For expansion into other countries, Fire TV is moving from per-country catalogs to Fire TV’s global catalog format. This catalog change enables an easier transition if included and launched as part of your global catalog. However, Fire TV still supports per-country catalogs.

Amazon content ID

Vega Content Personalization supports content identification across different namespaces. All content IDs must be passed with an associated namespace in order for Amazon to identify the content item. Amazon supports the following namespace:

Namespace	Description
`cdf_id`	The content ID namespace for Amazon catalog integration. Use the content ID from your catalog file. In the Enhanced Metadata Bridge for Entertainment Resources (EMBER) schema, this is the `id` attribute on program elements such as `Movie`, `TVEpisode`, and `TVSeries`. In the legacy Catalog Data Format (CDF), this corresponds to the `ID` field of a work.

Amazon profile ID

All data types allow you to share an associated profile ID. Since there are different profile types, specify the namespace. Amazon currently supports the following profile ID namespace:

Namespace	Description
`app_internal`	This namespace means you’re sharing a string representation of your internal profile ID for the active profile. This ID identifies specific profiles in your app to attribute activity to the right Fire TV profile. Don’t provide the actual ID you use internally. This value shouldn’t identify the customer. Use a hash value of your internal profile ID, which should be the same across all devices. Also, don’t send the profile name provided by the customer. Even if your app doesn’t use profiles, provide a consistent value.

Reporting updates

The SDK contains functionality to share information using three types of operations:

New (example: reportNewCustomerListEntry) - Represents an incremental update to add a new entry to the dataset.
Removed (example: reportRemovedCustomerListEntry) - Represents a decremental update to remove an entry from the dataset.
Refreshed (example: reportRefreshedCustomerList) - Indicates changes to the dataset due to off-device action, and a new refreshed version of the list must be fetched using the data pull service.

New and Removed are useful when the customer interacts with content in the app, and it performs adds or removes. The Refreshed update is useful when there are significant changes to the list due to customer sign-in, off-device activity, or if you suspect the list is out of sync for another reason.

Providing large sets of data

When supplying large amounts of data through the data pull service, pull the data in reasonably small pages from your cloud backend and call the provider APIs as the data is being pulled down. This pull amount limits memory usage for your service and prevents your app from being terminated by the system.

const customerListEntriesHandler: ICustomerListEntriesHandler = {
   getAllCustomerListEntries: (
      listType: CustomerListType,
      provider: ICustomerListEntriesProvider,
   ) => {
      let myCloudHasMoreData = true;
      while(myCloudHasMoreData){
            let myCloudResponse = getNextPageFromMyBackend();
            let myCloudData = myCloudResponse.getData();
            let entries: ICustomerListEntry[] = [];
            for(let element in myCloudData){
               let entry = <build data with CustomerListEntryBuilder>
               entries.push(entry)
            }
            provider.addCustomerListChunk(listType, entries);

            myCloudHasMoreData = myCloudResponse.hasMoreData();
      }
      provider.commit();
   },
};

​Prerequisites

​Integration steps

​Step 1. Include the package dependencies in your app

​Step 2. Update your manifest file

​Step 3. Make a sample API call

​Step 4. Validate the integration

​Step 5. Make API calls as part of in-app functionality

​Step 6. Implement your data pull service for background or off-device data

​Make changes to your catalog integration when directed by your Amazon contact

​Amazon content ID

​Amazon profile ID

​Reporting updates

​Providing large sets of data