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:
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.
- 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 ContentID 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 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:
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.
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 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
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|
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.
|live||Stream to be launched into||Live 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.
If your content is Note #2: 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 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: