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

Content Launcher Integration Guide

This document explains how to integrate Content Launcher into your app. Media apps typically require integration with three key APIs:

  1. The Content Launcher API
  2. Vega Media Controls API
  3. Account Login API

The system implements Content Launcher and Vega Media Controls APIs as in an interactive component, which is the main component handling Vega media queries. The Account Login API functions as a service component.

Step 1: Update your App's manifest file

In your app's manifest.toml file, include Content Launcher support. This example assumes your package ID is com.amazondeveloper.keplervideoapp. Replace this package ID with your app's package ID.

Configure your app to interact with the Vega Media Content Launcher APIs.

Copied to clipboard.

schema-version = 1

[package]
title = "<Your app title>"
id = "com.amazondeveloper.media.sample"

[components]
[[components.interactive]]
id = "com.amazondeveloper.media.sample.main"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"
# The category "com.amazon.category.kepler.media" is only necessary for the primary component, which is identified in the [[extras]]
# section of the manifest using the "component-id" value.
categories = ["com.amazon.category.main", "com.amazon.category.kepler.media"]

[processes]
[[processes.group]]
component-ids = ["com.amazondeveloper.media.sample.main"]

[offers]
[[offers.interaction]]
id = "com.amazondeveloper.media.sample.main"

[[message]]
uri = "pkg://com.amazondeveloper.media.sample.main"
# Match the privileges used in [[offers.interaction]]. If privileges are not added, then use "*".
sender-privileges = ["*"]
receiver-privileges = ["self"]

[[offers.module]]
id = "/com.amazondeveloper.media.sample.module@ISomeUri1" 
includes-messages = ["pkg://com.amazondeveloper.media.sample.main"]

[[extras]]
key = "interface.provider"

component-id = "com.amazondeveloper.media.sample.main"

[extras.value.application]
[[extras.value.application.interface]]
interface_name = "com.amazon.kepler.media.IContentLauncherServer"

# The "override_command_component" field is only necessary when the "component-id" specified in the [[extras]]
# section differs from the one you're providing here. This enables you to use a different component for
# command execution than the one initially defined in the extras, giving you flexibility in your
# configuration setup.

# For example, if you're using Account Login interface in addition to the Content Laucher interface
# you would need to override the Account Login status attribute to be directed to the service
# component with the following line:
# override_command_component = { Status = "com.amazondeveloper.media.sample.interface.provider" }
attribute_options = ["partner-id"]
static-values = { partner-id = "<Your partner id>" }

[needs]

[[needs.module]]
id = "/com.amazon.kepler.media@IContentLauncher1"

Step 2: Include the necessary package dependencies in your app

In the package.json file, add the @amazon-devices/kepler-media-content-launcher package as a dependency.

Copied to clipboard.

"dependencies": {
    "@amazon-devices/kepler-media-content-launcher": "^2.0.0",
},

Step 3: Implement the Content Launcher API

  1. Define the Content Launcher handler.

    Instantiate a new ContentLauncherServerComponent. Develop a handler object that encapsulates the callback function.

    Copied to clipboard.

    import {
ILauncherResponse,
IContentLauncherHandler,
ContentLauncherStatusType,
ContentLauncherServerComponent,
IContentSearch,
ILaunchContentOptionalFields,
} from '@amazon-devices/kepler-media-content-launcher';

...
// Create an instance of ContentLauncherServerComponent
let factory = new ContentLauncherServerComponent();

// Create a handler that is called when content is requested to be launched.
const contentLauncherHandler: IContentLauncherHandler = {
   async handleLaunchContent(
      contentSearch: IContentSearch,
      autoPlay: Boolean,
      _optionalFields: ILaunchContentOptionalFields,
   ): Promise<ILauncherResponse> {
      console.log('Content_Launcher_Sample: handleLaunchContent invoked');

      //Iterate here to fetch data,
      //business logic to handle launch request

      let launcherResponse = factory
            .makeLauncherResponseBuilder()
            .contentLauncherStatus(ContentLauncherStatusType.SUCCESS)
            .build();
      return Promise.resolve(launcherResponse);
   },
};

    The handler should process the request, return a Promise to ILauncherResponse, and create it with an instance of the ContentLauncherServerComponent. Set the status of contentLauncherStatus for LauncherResponse to ContentLauncherStatusType.SUCCESS if your app successfully processed the request. Set the status to ContentLauncherStatusType.AUTH_FAILED if your app can't process the request due to authorization issues. Set the status to ContentLauncherStatusType.URL_NOT_AVAILABLE for everything else.

  2. Implement the Vega Media Content Launcher in your interactive app.

    To implement the Vega Media Content Launcher in your interactive app, start by obtaining a singleton instance of IContentLauncherServerAsync. Implement IContentLauncherServerAsync by using the getOrMakeServer method on your ContentLauncherServerComponent instance. Next, create a handler object implementing the IContentLauncherHandler interface to process content launch requests. Call the 'setHandlerForComponent' method for the 'IContentLauncherServerAsync' instance. This associates the handler with the correct component. Pass the handler and the appropriate IComponentInstance. In an interactive app, you can obtain the IComponentInstance using the useComponentInstance method. For React Native apps, set up the handler within the useEffecthook. It should initialize Content Launcher as soon as the component mounts and the IComponentInstance are available. This tightly integrates Content Launcher functionality with your component's lifecycle. It also lets your app to handle Vega Content Launcher commands efficiently from the moment it's initialized. This setup is important for apps with multiple components, so that each component uses IComponentInstance, preventing confusion in callback routing.

    Copied to clipboard.

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

export const App = () => {

const componentInstance: IComponentInstance = useComponentInstance();

useEffect(() => {
   const factory = new ContentLauncherServerComponent();

   const contentLauncherHandler: IContentLauncherHandler = {

      async handleLaunchContent(
      contentSearch: IContentSearch,
      autoPlay: boolean,
      _optionalFields: ILaunchContentOptionalFields,
      ): Promise<ILauncherResponse> {
      console.log('Content_Launcher_Sample: handleLaunchContent invoked.');

      // Iterate to fetch data..
      //..here

      const launcherResponse = factory
         .makeLauncherResponseBuilder()
         .contentLauncherStatus(ContentLauncherStatusType.SUCCESS)
         .build();

      return Promise.resolve(launcherResponse);
      },
   };

   const contentLauncherServer = factory.getOrMakeServer();
   contentLauncherServer.setHandlerForComponent(contentLauncherHandler,componentInstance);

   return () => {};
}, []);

// Create a user interface for your provider app here.
};

Implementation details

The IContentLauncherHandler handler takes three parameters that define what content to play or show search results.

  • A pointer to an object implementing IContentSearch interface.
  • A boolean value called autoPlay.
  • Optional additional fields passed through a pointer to an object implementing the ILaunchContentOptionalFields interface.

Use autoPlay to determine what action to perform.

If autoPlay is true, it is a quick play request. Requested content should start playing directly without further interaction by the user. If autoPlay is false, then show the search results. The user can then review and select from the available options.

Retrieve contentSearch:IContentSearch values.

This parameter includes the content the user sent by Content Launcher and Alexa. The following schema is for the values stored in contentSearch:IContentSearch.

1    "parameterList": [{
1.1     "type": "<entity type>",
1.2     "value": "<entity value>",
1.3     "externalIdList": [{
1.3.1          "name": "<externalId name>",
1.3.2          "value": "<externalId value>"
        }]
      }]

1 ParameterList has one or more entries. Use contentSearch.getParameterList().length to retrieve the full list.

1.1 <entity type> represents the type of the entity listed in the parameter. For a list of all supported entity types, see Enumeration ContentSearchParamType. For example, "type" is "ContentSearchParamType::VIDEO" if it's a movie or TV Show. Call getParamType() to fetch the type.

1.2 <entity value> represents the value of the entity mentioned in the type. Call getValue() to retrieve this field.

1.3 parameterList has one or more external IDs. Use getExternalIdList().length to get the size of the list. getExternalIdList() provides the full list of externalIdList.

1.3.1 getName() usually retrieves the <externalId name>. If the externalId name is amzn_id, look for its value.

1.3.2 <externalId value> represents the value of the externalId. To retrieve the value, use getValue(). getValue() contains the same <ID> or <launchId> values used in your catalog integration, letting you to know which content the user wants to watch.

Example: Extract and search for the requested search parameter

The following code example demonstrates how to extract and search for the requested search parameter. This approach consolidates various pieces of information into a single string that you can modify to and use within the handleLaunchContent method.

This example launches an episode using the following Alexa utterance: "watch The SeaShow: The Real Story, season two, episode five in Streamz."

Copied to clipboard.

// Iterator to fetch data.
let searchParameters = contentSearch.getParameterList();
if (searchParameters.length > 0) {
   for (var j = 0; j < searchParameters.length; j++) {
      let paramType = searchParameters[j].getParamType();
      let searchString = searchParameters[j].getValue();

      let additionalInfoList = searchParameters[j].getExternalIdList();
      for (var i = 0; i < additionalInfoList.length; i++) {
         let searchName = additionalInfoList[i].getName();
         let entityID = additionalInfoList[i].getValue();

         if (searchName == 'amzn_id') {
         // Use this entity ID to get exact content from your catalog.

         } else {
            // ex:
            // entityID= "ENTITY_ID" :
            // searchName = "amzn1.p11cat.merged-video.087c9371-6bb7-5edb-bcef-f8717fde0a8a"
            //
         }
      }
   }
   if (autoPlay) {
      console.log(`Content_Launcher_Sample: Quickplay`);

      // Handle play logic here using the data retrieved above.
   } else {
      console.log(`Content_Launcher_Sample: In-App search`);

      // Handle search logic here using the data retrieved above.
   }
} else {
   console.log('Content_Launcher_Sample: Error fetching search string');
}
// Iterator to fetch data.

Content Launcher request examples

The following examples explain contentSearch parameter values for some key Content Launcher use cases. This example lists all supported use cases. Content Launcher is invoked and the app launches for every use case.

The following sample catalog for streamz_us includes example entries for the movie Seabound and the TV show The SeaShow: The Real Story.

Copied to clipboard.

...
<Movie>
  <ID>1700000725</ID>
  <Title locale="en-US">Seabound</Title>
  <Offers>
    <SubscriptionOffer>
      <LaunchDetails>
        <Quality>UHD</Quality>
        <Subtitle>en-US</Subtitle>
        <LaunchId>tv.streamz/movie/46720001</LaunchId>
      </LaunchDetails>
    </SubscriptionOffer>
    <FreeOffer>
      <Regions>
        <Territories>US</Territories>
      </Regions>
      <LaunchDetails>
        <Quality>SD</Quality>
        <Subtitle>en-US</Subtitle>
        <LaunchId>tv.streamz/movie/467200002</LaunchId>
      </LaunchDetails>
    </FreeOffer>
  </Offers>
</Movie>

<TvShow>
  <ID>1700000123</ID>
  <Title locale="en-US">The SeaShow: The Real Story</Title>
  <Offers>
    <FreeOffer>
      <Regions>
        <Territories>US</Territories>
      </Regions>
      <LaunchDetails>
        <Quality>HD</Quality>
        <Subtitle>en-US</Subtitle>
        <LaunchId>459800033</LaunchId>
      </LaunchDetails>
    </FreeOffer>
  </Offers>
</TvShow>

<TvSeason>
  <ID>1700000234</ID>
  <Title locale="en-US">Season 1</Title>
    <Offers>
     <FreeOffer>
       <Regions>
         <Territories>US</Territories>
       </Regions>
       <LaunchDetails>
         <Quality>HD</Quality>
         <Subtitle>en-US</Subtitle>
         <LaunchId>453200012</LaunchId>
        </LaunchDetails>
     </FreeOffer>
   </Offers>
   <ShowID>1700000123</ShowID>
   <SeasonInShow>2</SeasonInShow>
</TvSeason>

<TvEpisode>
  <ID>1700000825</ID>
  <Title locale="en-US">The Seashow. Story Starts</Title>
  <Offers>
    <FreeOffer>
      <Regions>
        <Territories>US</Territories>
      </Regions>
      <LaunchDetails>
        <Quality>HD</Quality>
        <Subtitle>en-US</Subtitle>
        <LaunchId>453100008</LaunchId>
      </LaunchDetails>
    </FreeOffer>
  </Offers>
  <ShowID>1700000123</ShowID>
  <SeasonID>1700000234</SeasonID>
  <EpisodeInSeason>5</EpisodeInSeason>
</TvEpisode>
...

Launch content through the remote

Launch the movie Seabound using a remote from the Vega TV Home screen.

Copied to clipboard.

"parameterList": [
  {                                           // parameter 0
      "type": 13,                             // ContentSearchParamType::VIDEO,
      "value": ,                              // Content title will not be populated
      "externalIdList": [{
          "name": "catalogContentId",          // Will be deprecated. Ignore this
          "value": "tv.catalog/movie/46720000" // ID or LaunchId from catalog
      }, 
      {
          "name": "amzn_id",          
          "value": "tv.catalog/movie/46720000" // ID or LaunchId from catalog
      }
     ]
  }
]

The app should identify the movie using tv.streamz/movie/46720000 for the LaunchId, and play it directly.

Quickplay with voice

Play movie Seabound through voice. Use the utterance "Alexa, Play Seabound."

autoPlay will be true here. The following example includes the contentSearch: IContentSearch values. The app launches and it should play content directly using ID 1700000725.

Copied to clipboard.

[
    {                             // parameter 0
        "type": 13,               // ContentSearchParamType::VIDEO
        "value": "Seabound",      // search string
        "externalIdList": [{
            "name": "streamz_us"   // your catalog id. Will be deprecated. Ignore this
            "value": "1700000725" // ID from catalog
        },
        { 
            "name": "amzn_id"  
            "value": "1700000725" // ID from catalog
        }
      ]
    }
]

Playing a specific episode with voice

The following catalog sample represents a TV Show SeaShow: The Real Story, its season, and an episode. The Alexa utterance "Alexa, Play Season 2 Episode 5 from The SeaShow: The Real Story," invokes the app to play the specific episode.

autoPlay will be true here. contentSearch includes the show ID, not the episode ID. The app must identify the exact episode using ID 1700000123, ContentSearchParamType::SEASON, and ContentSearchParamType::EPISODE values.

Copied to clipboard.

[
  {                // parameter 0
    "type": 13,    // ContentSearchParamType::VIDEO
    "value": "Season Two Episode Five The SeaShow: The Real Story", 

    "externalIdList": [{
       "name": "streamz_us",   // Will be deprecated, Ignore this
       "value": "1700000123" // ID of the Show from catalog
     },
     {
      "name": "amzn_id",
      "value": "1700000123" // ID of the Show from catalog
    }]
  },
  {                // parameter 1
    "type": 14,    // ContentSearchParamType::SEASON
    "value": "2",  // Season number in catalog
    "externalIdList": []
  },
  {               // parameter 2
    "type": 15,   // ContentSearchParamType::EPISODE
    "value": "5", // episode number in catalog
    "externalIdList": []
  }
]

In-app search for a content title using voice

Search for the movie Seabound, using voice. Use the utterance "Alexa, find Seabound in Streamz."

The app must show the search result with Seabound and related content. The app decides on the search logic. autoPlay will be false here. contentSearch: IContentSearch values are as follows.

Copied to clipboard.

[
  {                      // parameter 0
    "type": 13,          // ContentSearchParamType::VIDEO
    "value": "Seabound", // Search keyword to use in search
    "externalIdList": [{
        "name": "streamz_us",  // Will be deprecated. Ignore this
        "value": "1700000725"  // ID from catalog
    },
   {
        "name": "amzn_id",
        "value": "1700000725" // ID from catalog
    }
   ]
  }
]

In-app search for a genre using voice

Search for a genre using voice with the utterance "Alexa, find comedy movies in Streamz."

autoPlay will be false. contentSearch: IContentSearch should have the following values. Alexa returns multiple genres and types. You can chose your own logic to implement search.

Copied to clipboard.

 [
  {                               // parameter 0
    "type": 6,                    // ContentSearchParamType::GENRE
    "value": "Comedy",           // Search keyword to use in search
    "externalIdList": []
  },
 {                                // parameter 1
    "type": 6,                    // ContentSearchParamType::GENRE
    "value": "Dark Comedy",       // Search keyword to use in search
    "externalIdList": []
  },
 {                                // parameter 2
    "type": 6,                    // ContentSearchParamType::GENRE
    "value": "Romantic Comedy",   // Search keyword to use in search
    "externalIdList": []
  },
 {                                // parameter 3
    "type": 13,                   // ContentSearchParamType::TYPE for VIDEO
    "value": "comedy movies",     // keyword to use in search
    "externalIdList": []
  }
]

In-app search for an actor using voice

Search for an actor using voice with the utterance "Alexa, find Sean Connery movies in Streamz."

autoPlay will be false. contentSearch: IContentSearch has following values.

Copied to clipboard.

[
  {                                 // parameter 0
    "type": 0,                      // ContentSearchParamType::ACTOR
    "value": "Sean Connery"         // Keyword to use in search
    "externalIdList": []
  },
  {                                    // parameter 1
    "type": 13,                       // ContentSearchParamType::TYPE for VIDEO
    "value": "Sean Connery movies",   // Keyword to use in search
    "externalIdList": []
  }
]

Last updated: Feb 11, 2026

Follow us:
amazon_developer_logo

© 2010-2026, Amazon.com, Inc. or its affiliates. All Rights Reserved.

Terms

Amazon Developer Blog

Contact Us