Table of Contents
Overview of deep linking
Deep linking lets other parts of the system launch a particular piece of content using parameters passed to the channel at launch time, rather than launching the home page for the channel.
When you created your channel, you defined meta-data for your channel and created a
contentID for each of your content items.
To implement deep linking, you parse the associative array passed in to your channel's main entry point — usually main() in the
There are two keys in this associate array that will be defined for the channel to be deep linked to:
|contentID||Unique identifier you define for a specific piece of content.|
Any ASCII String < 255 characters long
|mediaType||Identifies the type of media to give context to the type of contentID passed.|
"series", "season", "episode", "movie", "short-form", "special" and "live"
Basic steps to implement deep linking
Step 1: Modify your channel to handle deep linking by editing your channel's main() or runuserinterface(). (See the section “Implementing deep linking in a channel” below.) Add one argument to the function, name it "args".
Step 2: Test args[contentID] and args[MediaType] <> invalid. If they have values, then the channel is being deep linked too. Otherwise, do a normal channel launch.
Step 3: Depending on the
mediaType parameter, your channel should play the content immediately or should allow the user to choose which episode to play. For a movie, episode, series, short-form, special or live stream you must playback the specified piece of content immediately. For a TV season, users must choose an episode from the season's episode picker screen.
Step 4: If you are implementing "series", then implement bookmarking using an event handler.
This is a timer that runs while you are playing content and periodically saves the location to your back-end.
What is a contentID?
A contentID is a unique ID that is associated with a single piece of content as defined for your channel using the attributes on Content Meta-Data. It is required so Roku can confirm that the content associated with a specific ID launches the deep link correctly.
Roku Search is not required for channel certification but if you do implement it, for each piece of content use the same
contentID you use for deep linking. In the XML feed Roku Search uses, a
contentID is identified with the tag
playID but it should use the same string as
contentID and identify the same piece of content.
The following example
contentID string shows how the
contentID can be split into segments if that helps you track the specific item:
contentID often consists of several other IDs that are used by the channel itself to identify the movie.
Requirements for a contentID
The format of a
contentIDis defined by the partner or content provider. Roku treats the
contentIDas an opaque string, meaning that we allow you to define your own naming convention. However, it is important that you maintain absolute consistency with this naming convention.
The contentID is an immutable value to identify a specific piece of content. The ID must identify the same content for all time.
The contentID is a single string and is no more than 255 characters in length.
The contentID must be URL encoded and cannot contain “&” characters.
The contentID must be passable as a command-line argument in a cURL command.
What is a mediaType?
A mediaType is used to categorize each type of content available on your channel. See MediaType and Behavior for more information.
NOTE: To pass certification, you must submit working sample deep links for each type of media in your channel.
Supported types of media are:
Requirements for deep linking behavior
To ensure a standard user experience across the Roku platform, Roku has defined a set of expected behaviors that a channel must exhibit when responding to a deep link request.
Your channel must support as many or as few
mediaTypeas is necessary to accurately index all the content in your channel. If your channel has a mix of TV shows and feature-length films, you must support the “movie,” “series,” “season,” and “episode”. If instead, your channel has many live feeds available at a time, use the “live”
mediaType. The one exception to this rule is for channels that only include one single live stream. Since such channels only have one possible behavior, there are no extra steps required from the developer.
- Channels must handle invalid deep links gracefully and should not cause a crash. When deep linking with an invalid
contentID, the link should be set to return to the home screen of the channel.
- Your channel must handle unauthenticated users who are deep linking into your channel or launching your channel for the first time. For example, this can happen when a user is deep linking into your channel from an ad or by using Roku Search for the first time. If the channel is uninstalled, Roku OS will prompt the user to install the channel before continuing with the deep link. Your code must route the user to the appropriate screen and then, when the user is authenticated, fulfill the deep link.
- If your channel requires a purchase prior to launching, you are allowed to display a purchase screen before the user sees the content.
- If your service supports profiles, you must set a default profile for a movie, episode or series. Do not force a customer to choose a profile prior to playing a movie or episode. This is because Roku does not allow any screen (except a purchase or authentication screen) to be presented to the customer between choosing a movie or episode and playing it. Which profile you select as the default is your decision, but Roku recommends the last profile the customer used.
MediaType and required behavior
When many types of media are launched with a deep link, the expected behavior is to begin playing the content directly. However, for the
season, the user should be brought to an episodic picker screen.
|Movie to be played|
For a movie or an episode, 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.
Note: There are several acceptable ways for a channel to respond to a series contentID. Your channel must always launch directly into video playback of an episode, but determining which specific episode to launch is defined by your channel. See Behavior for Deep Linking to a Series for guidance.
|Episode to be played|
|contentID of an episode in the series|
|Item to be played||If your content is a movie trailer, news clip, digital short, or must stand-alone content less than 15 minutes in duration, it is likely considered a |
contentID to be played
|contentID of an episode in the season||For |
|Stream to be launched||Use |
Behavior for deep linking to a series
When a channel is passed the
series mediaType, it will receive a contentID that can be used to identify the content to be played. The contentID passed may not be the specific episode that should be played; rather, it can be used to indicate the series. Once the series is identified, the channel should implement its own logic to start playback at the best position in the series possible, based on the user's past viewership of the series and based on the type of series.
In most cases, the channel should refer to a smart bookmark on their service's backend to determine where in the series' chronology the user last watched, and resume playback from that position. This may be in the middle of an episode, the start of the next episode in the series, or, if the user has never watched an episode from that series at all, it may be the beginning of the very first episode in the series.
In some cases, this implementation might not make sense. For instance, if a user deep links to a nightly news series, it is reasonable to assume they want to watch tonight or last night's news, as opposed to the very first episode ever aired as part of that news series. In this case, the channel service should be intelligent enough to initiate playback of the most recent episode of the series.
Remember: There is no "series" contentID. "Series" is only a mediaType. Use an episode contentID to identify the content to be played.
Keep in mind that there are many different types of content series: Serialized television dramas, reality TV, sitcoms, nightly news, talk shows, etc. As such, there are several different ways you could choose to respond to a
series deep link in order to build the best user experience.
Below are some common types of series and Roku’s recommended deep linking behavior for each:
|Type of Series||Definition||Recommended Behavior|
|Current TV Series|
A series that the user has already started watching in the past.
|Using the user’s bookmarked position, bring the user to the next episode in the series from where they last watched. Or, if they did not watch the last episode to completion, drop them into the moment where they last left off.|
|Library TV Series||A cataloged series that the user has not yet watched on your service.||Drop the user directly into video playback at the beginning of Season 1 Episode 1.|
|Daily or Weekly Shows||A regularly-occurring show that does not necessarily need to be watched in chronological order. News broadcasts, talk shows, sports podcasts, or religious sermons are examples of this type of series.||Play the most recent episode of the series.|
Implementing deep linking in a channel
Deep linking is implemented by passing launch parameters to your channel's
Main() function. These launch parameters are passed in using an associative array similar to
argv in C. Your channel is responsible for parsing these parameters and taking the appropriate action, or in the case of an error, detecting it and going to the channel's home screen.
The first step is to modify the
Main() function for your channel to accept the two deep linking parameters by adding a variable. This variable can be any arbitrary name. In this example, the variable name
args is used.
Function Main (args as Dynamic) as Void
Then, determine if the channel is being launched via a deep link. If either
invalid, disregard the deep link and launch the channel normally.
Example of a m
ain.brs file for a basic channel that requires no authentication:
sub Main() print "in showChannelSGScreen" 'Indicate this is a Roku SceneGraph application' screen = CreateObject("roSGScreen") m.port = CreateObject("roMessagePort") screen.setMessagePort(m.port) 'Create a scene and load /components/yourchannel.xml' scene = screen.CreateScene("Hello Channel") screen.show() while(true) msg = wait(0, m.port) msgType = type(msg) if msgType = "roSGScreenEvent" if msg.isScreenClosed() then return end if end while
Testing Deep Linking
You can test your deep links using cURL or by using the Roku Deep Linking Tester tool.
Using the Deep Linking Tester
The Roku Deep Linking Tester tool allows you to do a test of your deep links prior to it going through the testing certification process.
NOTE: Roku highly recommends you use this tool as deep links must work for your channel to pass certification.
- Use the Roku Deep Linking Tester: https://devtools.web.roku.com/DeepLinkingTester/
- Use the associated Roku Deep Linking Tester channel: https://my.roku.com/account/add?channel=KX3UPK
This tool requires the same deep linking attributes as defined for cURL, but provides a UI plus other features to help, such as saving deep linking parameters to reuse.
Using cURL for Testing
Deep linking can be tested using cURL and the External Control Protocol (ECP).
You can trigger deep linking by doing an HTTP post to port 8060 on your Roku device. The form of the cURL is:
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|
The following example shows the cURL for a side-loaded channel with a mediaType of
movie and a contentID of
Submitting deep linking content for certification
When submitting a channel for certification, you are required to provide one or many pairs of deep link parameters, dependant on how many unique mediaTypes your channel includes. These deep link parameters should be provided in the "Test Accounts & Deep Linking Parameters" field on the Support Information page of the channel submission survey found within the Developer Dashboard.
You are required to provide one pair of deeplinking parameters for each type of media included in your channel. These parameters are used by Roku to certify that your channel is responding with the correct behavior for each type of content in your channel.
On the Support Information screen of the channel submission survey, you can enter your deep linking content by pasting in your
contentID, such as a movie's deep linking parameters:
The following illustrates the location in the Support Information screen: