Table of Contents
What is Deep Linking?
Deep linking describes the process of launching specific pieces of content.
All public Roku channels are required to implement Deep Linking in order to pass certification. Important:
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.
- Use the Deep Linking Test Tool: https://devtools.web.roku.com/DeepLinkingTester/
- And use the associated Roku channel: https://my.roku.com/account/add?channel=KX3UPK
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 Content ID Format, Guideline, and Requirement?
The following guideline and requirement for a Content ID are as follows:
- The format of
contentIDis 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 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:
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 all content types that are in your feed. See the MediaType, Required Behavior, and User Experience section in this document for more details.
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. Important:
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: https://devtools.web.roku.com/DeepLinkingTester/ and the associated Roku channel: https://my.roku.com/account/add?channel=KX3UPK.
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. 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?
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.
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
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:
|Movie 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.|
|Episode to be played|
|Item to be played|
|contentID of an episode in the season|
Go to an episodic picker screen for this season. Select the episode who's c
If your Media Type is Season, and your channel has a grid presentation, deep link: mediatType = “seasons” and highlight the first episode.
The required behavior is to go to the episodic picker screen for this season. The episode whose ContentId was passed in should be selected. Content should not autoplay.
Note: If your content does not match a particular MediaType, use
If your content is Note: composed of speeches and does not contain movies or seasons, then the
short-form mediaType would be acceptable.
If you happen to Deep Link with invalid media, the link will return to the home screen of the channel page. Note:
Testing Deep Linking
Deep linking can be tested using cURL. The following attributes are required:
|IP Address||IP address of the Roku device with the channel sideloaded or installed||192.168.1.114|
|mediaType||the mediaType of the content to deep link to||season|
|contentID||the contentID of the content to deep link to||1234|
See the following example: