Skip to end of metadata
Go to start of metadata

Table of Contents

Overview of Deep Linking

 Deep linking describes the process of launching specific pieces of content. It is based on Roku Search.

  Important:  All public Roku channels are required to implement deep linking in order to pass certification.

  Important:  You must submit working sample deep links with your channel certification.

Where is the Deep Linking Tester Tool?

The Deep Linking Tester Tool allows you to do a thorough test of your content prior to it going through the testing certification process.

We highly recommend you use this tool to help assure that your certification goes through the first time you submit your content.

This tool requires the same deep linking attributes but provides a UI and other features like saving prior deep linking parameters to reuse.

What is a contentID?

A contentID is a unique ID that is associated with a single piece of content in your feed. It is required so Roku can confirm that the content associated with a specific ID launches when testing your deep linking implementation. contentIDs are created/defined by the channel. 

What is the contentID Format, Guideline, and Requirement?

The requirements for a contentID are as follows:

  • The format of contentID is defined by the partner or content provider. We treat the contentID as an opaque string, meaning that we allow you to define your own naming convention. That being said, it is important that you maintain absolute consistency with this naming convention.

  • The contentID is an immutable value to identify a specific piece of content. The ID must identify the same content for all time.

  • The contentID is a single string and is no more than 255 characters in length.

  • The contentID cannot contain “&” characters.

  • The contentID must be passable as a command-line argument in a curl command.


Example string:


What is a mediaType?

mediaType is used to categorize the types of content in your feed according to Roku standards. mediaType options are limited to movie, series, season, episode, short-form, special, and live.

Your channel must support as many or as few mediaType as is necessary to accurately index all the content in your channel. If your channel has a mix of TV shows and feature-length films, then you must support the “movie,” “series,” “season,” and “episode” mediaTypes. If instead your channel has many live feeds available at a time, then use the “live” mediaType.

The one exception to this rule is for channels that only include one single live. Since such channels only have one possible behavior, there are no extra steps required from the developer.

See the mediaType, Required Behavior, and User Experience section in this document for more details.

How do I Implement Deep Linking in a Channel?

Steps to implement your deep linking channel are as follows:

Step 1: Channel is launched with deep linking arguments that include mediaType and contentID. 
             To assist you with choosing a MediaType see the mediaType, Required Behavior, and User Experience section in this document.

Step 2: Depending on the mediaType parameter, either play content directly or allow the user to choose which episode to play.

Step 3: Use the Deep Linking Tester Tool and the associated Roku channel.
             This will help assure that your submission for certification goes through properly (see Step 5).

Step 4: Enter your content into the form field and submit for certification review. See the following example:


Step 5: Your channel will be reviewed and tested before it is allowed to launch. If there are errors, you will be notified to make modifications before resubmitting. 

Note: If your service supports profiles, you must set a default profile for a movie, episode or series. Do not force a customer to choose a profile prior to playing a movie or episode. This is because Roku does not allow any screen (except a purchase screen) to be presented to the customer between choosing a movie or episode and playing it. Which profile you select as the default is your decision, but Roku recommends the last profile the customer used.

Final Note to Developers: Deep linking is implemented by passing parameters to the Main() function. These launch arguments are passed in using an associative array similar to argv in C. The channel is responsible for parsing these parameters and handling the appropriate action, or in the case of an error, detecting it and going to the channel's main screen. Channels must handle invalid deep links gracefully and should not cause a crash.

How Do I Submit Deep Linking Content for Certification? 

The following illustrates the location on the online form where you enter your deep linking content.

What is the Requirement Difference between Global Search, and Deep Linking?

Global search is optional, whereas deep linking is not. Deep linking is a requirement for Roku Channel certification.

What about Authenticated vs. Non-Authenticated Users or Free vs. TVOD content?

Something to consider when designing this flow is handling unauthenticated users. Users may be deep linking and installing/launching the channel for the first time. This can happen using Roku Search and will prompt the user to install the channel before continuing with the deep link. Your code must route the user to the appropriate screen, but then must continue on to fulfill the deep link.

Parameters and Arguments

Accepting Deep Linking Parameters in Main()

The first step is to modify the Main() function to accept the deep linking parameters in BrightScript. This variable can be any arbitrary name. For this example we will be referred to the variable name as args as shown below.

Parsing and Handling the Arguments

The first thing you want to do in your channel is parse the arguments and determine if the channel is being launched via a deep link. If either args.contentID or args.mediaType is invalid, disregard the deep link and launch the channel normally.

Example (with no authentication or entitlement required)

If you have a channel which erquires authentication or requires a purchase, you are allowed to put that screen up before you enter that content.

mediaType, Required Behavior, and User Experience

To ensure a standard user experience across the Roku platform, Roku has defined a set of expected behaviors that a channel must exhibit when responding to a deep link request. In almost all cases, the expected behavior is to launch right into content playback. The single exception to this rule is for the mediaType season, in which case the user should be brought to an episodic picker screen.

Below is a list of all mediaTypes and their corresponding required behavior:

 MediaType must be one of the following values:

mediaTypecontentIDRequired Behavior
movieMovie to be played

The required behavior is to launch directly into playback. If the content is paywalled or the user is not authenticated, you can redirect to the appropriate screen. The user should be able to play content directly after the required action is performed.

Note: If your service supports profiles, you must set a default profile for a movie, episode or series. Do not force a customer to choose a profile prior to playing a movie or episode. This is because Roku does not allow any screen (except a purchase screen) to be presented to the customer between choosing a movie or episode and playing it. Which profile you select as the default is your decision, but Roku recommends the last profile the customer used.

Note: There are several acceptable ways for a channel to respond to a series contentID. In all cases, the channel must launch directly into video playback of an episode, but determining which specific episode is up to the channel partner. See the “Best Practices for Deep Linking to a Series” section for guidance.

episodeEpisode to be played
Series from which to play an episode


Item to be played 
seasoncontentID of an episode in the season

You are REQUIRED to go to a Picker Screen. Even if you normally do not have a Picker Screen, you are still required to implement one for deep linking. A Picker Screen is defined as a screen that only shows episodes from that particular show. The actual layout of the Picker Screen is not important: it could be a grid, a list, or something else.  You will need to select the episode passed in using the ContentID. In most cases this is the first episode but does not have to be.

liveStream to be launched intoLive is used when you are not identify a piece of content but instead a specific live feed (i.e. a channel). 

Note #1: If your content is composed of speeches and does not contain movies or seasons, then the short-form mediaType would be acceptable.

Note #2: Use special if your content does not match a particular MediaType.

Note #3: When deep linking with an invalid media type or ContentID, the link should be set to return to the home screen of the channel page.

Best Practices for Deep Linking to a Series

The "series" mediaType is meant to be a smart bookmark that will immediately start playing the best position in the series. There are many different types of content series: Serialized television dramas, reality TV, sitcoms, nightly news, talk shows, etc. As such, there are several different ways a channel partner could chose to respond to a series deep link.

Below are some common types of series and Roku’s preferred deep linking best practices for each one:

Type of SeriesDefinitionBest Practices
Current TV Series

A series that the user has already started watching

Using the user’s bookmarked position, bring the user to the next episode in the series from where they last watched. Or, if they did not watch the last episode to completion, drop them into the moment where they last left off. 
Library TV SeriesA catalogued series that the user has not yet watched on your serviceDrop the user directly into video playback at the beginning of Season 1 Episode 1. 
Daily or Weekly ShowsA regularly-occurring show that does not necessarily need to be watched in chronological order. News broadcasts, talk shows, sports podcasts, or religious sermons are a good example of thisPlay the most recent episode of the series.

Testing Deep Linking

Deep linking can be tested using cURL. The following attributes are required:

IP AddressIP address of the Roku device with the channel sideloaded or installed192.168.1.114
Port8060 is used for External Control Protocol (ECP) commands8060
ECP commandlaunch (additional ECP commands can be found here)launch
Channel ID
  • If the channel is sideloaded, use dev
  • If the channel is an installed public or non-certified channel, the channel ID can be found on the Developer Dashboard on the preview page for your particular channel or 
  • enter http://<roku-device-ip-address>:8060/query/apps in a web browser to see a list of installed channels (and the Channel IDs) on the Roku device.
mediaTypethe mediaType of the content to deep link toseason
contentIDthe contentID of the content to deep link to1234

See the following example:

Deep link example for a sideloaded channel with a mediaType of Season and a contentID of 1234
  • No labels