Skip to end of metadata
Go to start of metadata

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.

Sections:


Implementing Deep Linking in a Channel

There are 3 main steps in the deep linking flow:

  1. Channel receives arguments representing the deep linking parameters
  2. Parse the mediaType and contentID parameters from the arguments
  3. Depending on the mediaType parameter, 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 args 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)

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:

mediaTypecontentIDRequired Behavior
movieMovie to be playedPlay 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.
episodeEpisode to be played
short-formItem to be played
special
seasoncontentID of an episode in the seasonGo to an episodic picker screen for this season. Select the episode who's contentID was passed in. Do not autoplay the content.

If your content doesn't match a particular MediaType, use special.

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 movie or 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:

AttributeDescriptionExample
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 private 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.
dev
mediaTypethe mediaType of the content to deep link toseason
contentIDthe contentID of the content to deep link to1234
Deep link example for a sideloaded channel with a mediaType of Season and a contentID of 1234

Deep Linking Tester Tool

Another way to test deep linking is with 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 tool requires the same deep linking attributes but provides a UI and other features like saving prior deep linking parameters to reuse.

  • No labels