Content Launcher and Account Login Testing

Verify using Universal Search launcher UX

You can verify the Account Login thorough universal search from the Fire TV home screen.

Verify Content Launcher integration using the remote

Install and log in to your app.
From the Fire TV Home screen, search for your app’s content
On the content detail page, select “Watch Now.”

Expected result: Your app should launch automatically, once the Content Launcher handler is invoked, and playback of the selected contents should begin.

Verify Content Launcher integration using voice

Install and log into your app. While the app is running in the foreground, use a voice command (“Alexa…”) to play content available in your app. The Content Launcher handler is invoked, and your app properly handles the request and begins playback of the requested content. Example utterances:

“watch <movie name>”
“Watch <TV Show name> with season <number> and episode <number>”
“Watch comedy movies”

You can also verify your Account Login integration from the command line. Use this to debug and confirm that your app reports its login status correctly.

Prerequisites

You’ve enabled Developer Mode on your Vega device. For instructions, see Enable Developer Mode.
Your app is installed by sideloading, launched at least once, and is running in either the foreground or background. The app component shell won’t work on apps installed through Live App Testing or through the Appstore.

Enter the component shell

Once developer mode is enabled, enter your component shell and check the CLI.

vda shell -t component-id <your-component-id>
sh(<your-package>):/$ kcp-cli-v2 --help

The CLI is pre-installed at /usr/bin/kcp-cli-v2 and may be accessed through the component shell. To check your app’s login status from the component shell, run the following command.

kcp-cli-v2 account-login read-status --pkg-id "<your-package-id>"

Example:

kcp-cli-v2 account-login read-status --pkg-id "com.example.myapp"

Expected output:

Account login status: true

If the value is true, the app is SIGNED_IN. If it’s false, the app is SIGNED_OUT. To monitor login status changes in real time, use the watch-status command.

kcp-cli-v2 account-login watch-status --pkg-id "<your-package-id>"

Example:

kcp-cli-v2 account-login watch-status --pkg-id "com.example.myapp"

Expected output:

Account login status: false
SUBSCRIBE_RESPONSE_ACTION transaction_id=3739690471, subscription_id=808
Account login status: true
Account login status: false

The output stream updates when the status changes. Log in and out of your app while this command runs to verify status transitions. For detailed usage, run:

kcp-cli-v2 account-login --help

Verify SIGNED_IN: Log in to your app, then run account-login read-status. The status should return true.
Verify SIGNED_OUT: Log out of your app, then run account-login read-status. The status should return false.
Verify transitions: Run account-login watch-status, then log in and out of your app. Confirm the status updates each time.

Verify Content Launcher integration using KCP CLI

You can use the KCP CLI tool to invoke Content Launcher requests on your app. This allows you to test launch requests without the use of Universal Search, the remote, or voice commands.

Prerequisites

You’ve enabled Developer Mode on your Vega device. For instructions, see Enable Developer Mode.
You’ve installed and registered your app with KCP, and you’ve launched it at least once.

Add content search JSON

The --content-search parameter accepts a JSON object with the following structure:

{
  "parameter_list": [
    {
      "param_type": "<TYPE_VALUE>",
      "value": "<CONTENT_NAME>",
      "external_id_list": [
        { "name": "<PROVIDER_NAME>", "value": "<PROVIDER_CATALOG_ID>" },
        { "name": "amzn_id", "value": "<AMAZON_CATALOG_ID>" },
        { "name": "ENTITY_ID", "value": "<ALEXA_ENTITY_ID>" }
      ]
    }
  ]
}

Add external_id_list fields

Name	Description
`<PROVIDER_NAME>`	Your provider-specific catalog ID (for example, `myapp_us`)
`amzn_id`	The Amazon catalog ID for the content from your catalog integration
`ENTITY_ID`	(Optional) The Alexa entity ID associated with the content

Launch a movie by title

Simulating: “Alexa, Watch <Movie Name>”

kcp-cli-v2 content-launcher launch --pkg-id "com.example.myapp" --content-search '{"parameter_list":[{"param_type":13,"value":"Seabound","external_id_list":[{"name":"myapp_us","value":"1700000849"},{"name":"amzn_id","value":"1700000849"},{"name":"ENTITY_ID","value":"your-alexa-entity-id"}]}]}' --auto-play

Expected result: Your app should launch and begin playback of the requested movie.

Launch a specific season and episode

Simulating: “Alexa, Watch Season 1, Episode 3 in <Show Name>”

kcp-cli-v2 content-launcher launch --pkg-id "com.example.myapp" --content-search '{"parameter_list":[{"param_type":13,"value":"Seabound","external_id_list":[{"name":"myapp_us","value":"1700000849"},{"name":"amzn_id","value":"1700000849"},{"name":"ENTITY_ID","value":"your-alexa-entity-id"}]},{"param_type":15,"value":"3","external_id_list":[]},{"param_type":14,"value":"1","external_id_list":[]}]}' --auto-play

Parameter breakdown:

param_type	value	meaning
13	`"Seabound"`	Movie/Show title
15	`"3"`	Episode number
14	`"1"`	Season number
Expected result: Your app should launch and begin playback of Season 1, Episode 3 of the requested show.

Launch a specific episode (no season)

Simulating: “Alexa, Watch Episode 3 in <Show Name>”

kcp-cli-v2 content-launcher launch --pkg-id "com.example.myapp" --content-search '{"parameter_list":[{"param_type":13,"value":"Seabound","external_id_list":[{"name":"myapp_us","value":"1700000849"},{"name":"amzn_id","value":"1700000849"},{"name":"ENTITY_ID","value":"your-alexa-entity-id"}]},{"param_type":15,"value":"3","external_id_list":[]}]}' --auto-play

Expected result: Your app should launch and begin playback of Episode 3 of the requested show.

Launch a specific season

Simulating: “Alexa, Watch Season 1 in <Show Name>”

kcp-cli-v2 content-launcher launch --pkg-id "com.example.myapp" --content-search '{"parameter_list":[{"param_type":13,"value":"Seabound","external_id_list":[{"name":"myapp_us","value":"1700000849"},{"name":"amzn_id","value":"1700000849"},{"name":"ENTITY_ID","value":"your-alexa-entity-id"}]},{"param_type":14,"value":"1","external_id_list":[]}]}' --auto-play

Expected result: Your app should launch and begin playback of Season 1 (typically starting with Episode 1).

Search cases (currently supported only for specific apps)

Search for a movie (no auto-play)

Simulating: “Alexa, Search <Movie Name>”

kcp-cli-v2 content-launcher launch --pkg-id "com.example.myapp" --content-search '{"parameter_list":[{"param_type":13,"value":"Seabound","external_id_list":[{"name":"myapp_us","value":"1700000849"},{"name":"amzn_id","value":"1700000849"},{"name":"ENTITY_ID","value":"your-alexa-entity-id"}]}]}'

Expected result: Your app should display search results for the requested content.

Search by actor

Simulating: “Alexa, Find <Actor Name>”

kcp-cli-v2 content-launcher launch --pkg-id "com.example.myapp" --content-search '{"parameter_list":[{"param_type":0,"value":"Sean Connery","external_id_list":[{"name":"ENTITY_ID","value":"your-alexa-entity-id"}]},{"param_type":13,"value":"Sean Connery","external_id_list":[]}]}'

Expected result: Your app should display content associated with the specified actor.

Search by genre

Simulating: “Alexa, Find Comedy Movies”

kcp-cli-v2 content-launcher launch --pkg-id "com.example.myapp" --content-search '{"parameter_list":[{"param_type":6,"value":"Comedy","external_id_list":[{"name":"ENTITY_ID","value":"your-alexa-entity-id"},{"name":"tms","value":"4"}]},{"param_type":13,"value":"Comedy","external_id_list":[]}]}'

kcp-cli-v2 content-launcher launch --pkg-id "com.example.myapp" --content-search '{"parameter_list":[{"param_type":6,"value":"Comedy","external_id_list":[{"name":"ENTITY_ID","value":"your-alexa-entity-id"},{"name":"tms","value":"4"}]},{"param_type":13,"value":"Comedy","external_id_list":[]}]}' --auto-play

Expected result: Your app should display comedy content, or begin playback if --auto-play is specified.

Content search parameter types

Use the param_type field in your content search JSON to specify the type of search:

Type	Value	Description
ACTOR	0	Search by actor name
CHANNEL	1	Search by channel
CHARACTER	2	Search by character name
DIRECTOR	3	Search by director
EVENT	4	Search by event
FRANCHISE	5	Search by franchise
GENRE	6	Search by genre
LEAGUE	7	Search by sports league
POPULARITY	8	Search by popularity
PROVIDER	9	Search by provider
SPORT	10	Search by sport
SPORTS_TEAM	11	Search by sports team
TYPE	12	Search by content type
VIDEO	13	Search by video or title name
SEASON	14	Season number
EPISODE	15	Episode number

CLI test scenarios for Content Launcher

Basic movie launch: Send a launch request with --auto-play for a known movie title with valid external_id_list values. Verify your app launches and begins playback.
Season and episode launch: Send a launch request with season and episode parameters. Verify your app navigates to the correct episode.
Episode-only launch: Send a launch request with only an episode number. Verify your app navigates to the correct content.
Search results display: Send a launch request without --auto-play. Verify your app displays relevant search results.
Actor search: Send a launch request with param_type: 0 and an actor’s name. Verify your app displays content from that actor.
Genre search: Send a launch request with param_type: 6 and a genre. Verify your app displays or plays content from that genre.
Playback preferences: Send a launch request with --optional-fields specifying a playback position. Verify your app resumes at the correct timestamp.
Unknown content handling: Send a launch request for content that doesn’t exist in your catalog. Verify your app handles the request gracefully.

For detailed usage, run:

kcp-cli-v2 content-launcher --help

Troubleshooting

Issue	Solution
`kcp-cli-v2` not found	Verify the CLI is installed: `which kcp-cli-v2`
”No endpoint found for package id”	Ensure your app is installed and has been launched at least once so KCP recognizes its endpoint.
Connection errors	Verify the KCP service is running: `vlcm list` and look for `com.amazon.kcp.component.service`.

​Verify using Universal Search launcher UX

​Verify Content Launcher integration using the remote

​Verify Content Launcher integration using voice

​Verify Account Login integration using KCP CLI

​Prerequisites

​Enter the component shell

​Read Account Login status

​Subscribe to Account Login status changes

​Test CLI scenarios for Account Login

​Verify Content Launcher integration using KCP CLI

​Prerequisites

​Add content search JSON

​Add external_id_list fields

​Launch a movie by title

​Launch a specific season and episode

​Launch a specific episode (no season)

​Launch a specific season

​Search cases (currently supported only for specific apps)

​Search for a movie (no auto-play)

​Search by actor

​Search by genre

​Content search parameter types

​CLI test scenarios for Content Launcher

​Troubleshooting

Verify using Universal Search launcher UX

Verify Content Launcher integration using the remote

Verify Content Launcher integration using voice

Verify Account Login integration using KCP CLI

Prerequisites

Enter the component shell

Read Account Login status

Subscribe to Account Login status changes

Test CLI scenarios for Account Login

Verify Content Launcher integration using KCP CLI

Prerequisites

Add content search JSON

Add external_id_list fields

Launch a movie by title

Launch a specific season and episode

Launch a specific episode (no season)

Launch a specific season

Search cases (currently supported only for specific apps)

Search for a movie (no auto-play)

Search by actor

Search by genre

Content search parameter types

CLI test scenarios for Content Launcher

Troubleshooting