Skip to end of metadata
Go to start of metadata

Table of Contents


FAQ

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.

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 Content ID 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 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:

ContentID="MyGroup=abc|ProductID=1234|groupID=456"

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.

 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 Toolhttps://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 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
short-formItem to be played
special
seasoncontentID of an episode in the season

Go to an episodic picker screen for this season. Select the episode who's contentID was passed in. Do not autoplay the content.

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 special. 

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

 Note: If you happen to Deep Link with invalid media, the link will return to the home screen of the channel page.


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 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.
dev
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