Skip to end of metadata
Go to start of metadata

Table of Contents

What is Deep Linking?

Deep linking describes the process of launching specific pieces of content. 

  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?

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 following guideline and requirement for a Content ID are as follows:

  • The format of contentID is a 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 content ID is an immutable value for identify a specific piece of content.   The ID must identify the same content for all time.
  • The content ID is a single string with no more than 255 characters in length.
  • The content ID cannot contain “&” characters.
  • The content ID must be passable as a command line argument in a curl command.
    See the following example:

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, episode, short-form, special, season, and live.  Your channel is required to support “movies” and “season”.   If you have no movies or episodic content you obviously don’t have to support those types.   Your channel must support something.   If you channel only lets you choose between live feeds then use the “live” mediatype.  There is one exception.  If your channel only launch a single live feed then you don’t have to do anything.  See the MediaType, Required Behavior, and User Experience section in this document for more details.

 Important:  Series Media Type is not accepted. Channels are required to support deep linking for all content types in the channel's feed. Roku is no longer supporting the series MediaType; any content categorized with MediaType series should now work and/or be replaced with MediaType season.

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. 

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

Channel behavior can vary depending on mediaType. If the mediaType is season, an episodic picker type of screen should be shown and content should not play automatically. For all other mediaTypes, content should play automatically once the deep link is enacted.

 MediaType must be one of the following values:

mediaTypecontentIDRequired Behavior
movieMovie to be playedThe 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.
episodeEpisode to be played


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: Use special if your content does not match a particular MediaType.

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

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.

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