Deep linking describes the process of launching channels and media content through an ad, a search result, or the My Feed feature. In order to support the global search interface and advertising initiatives, all Roku channels with indexed content are required to respond to deep link requests. The following guide details how to integrate deep linking in your Roku channel. All public Roku channels are required to implement deep linking in order to pass certification.
Implementing Deep Linking in a Channel
There are 3 main steps in the deep linking flow:
- Channel receives arguments representing the deep linking parameters
- Parse the
contentIDparameters from the arguments
- Depending on the
mediaTypeparameter, either play content directly or allow the user to choose which episode to play
Deep linking is implemented by passing parameters to the
Main() function. These launch arguments are passed in via 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.
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 but it will be referred to as
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)
User Experience for Deep Linking
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||Play the content directly. If the content is behind a paywall or requires the user to be authenticated, the channel can redirect to the appropriate screen(s) to do so. The user should be able to play the 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 content doesn't match a particular MediaType, use
If you don't have a particular form of content you don't have to support deep linking for those mediaTypes. For example, a channel which is composed of speeches would not have movies or seasons. In this particular example, the
short-form mediaType would be acceptable. In general, try to implement
season first as those mediaTypes are what is currently used in Roku Search.
Format of contentID parameter
The format of
contentID is a defined by the partner or content provider. The only restrictions are the
contentID parameter must not exceed 255 characters and it must not contain any characters used in query string parameters (such as
Does the content require authentication?
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 via Roku Search and will prompt the user to install the channel before continuing with the deep link.
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|
Deep Linking Tester Tool
This tool requires the same deep linking attributes but provides a UI and other features like saving prior deep linking parameters to reuse.