Deep Linking allows your channel's video content to be directly accessed from outside of the channel.
For example, Deep Linking is used when a viewer selects one of your videos from Roku's Search screen.
Deep Linking is also used when a viewer clicks on a banner ad for your channel on the Roku Home screen.
Roku requires that you provide at least one example Deep Linking Content ID in order to validate that Deep Linking works in your channel.
Typically you only need to provide a Deep Linking Content ID for one video in your channel.
You do not need to provide Deep Linking Content IDs for all videos in your channel.
In order to use Deep Linking, the Theme DeepLinkingEnabled parameter must be set to "True", and the Theme DeepLinkingSpringboardEnabled parameter should usually remain at "False".
Older channels may need to have the Developer Mode on the Account page set to "Advanced" to view or change the Theme Deep Linking parameters.
The Content ID to use with Deep Linking is the value of the DeepLinkId parameter.
The DeepLinkId parameter is present in all video items and MRSS items created in channels at Update #465 or later.
If the DeepLinkId parameter is blank, or if the DeepLinkId parameter does not exist,
then the "Content UID" shown directly beneath the item's poster is used as the Deep Linking Content ID:
Each Deep Linking Content ID must be assigned a Media Type when submitted to Roku.
The following Media Types are accepted by Roku:
movie - A long-form film or movie.
shortFormVideo - An standalone content item of 15 minutes or less.
live - A live stream. Note: Roku does not require Deep Linking support for live streams unless the channel consists entirely of one or more live streams.
episode, season, or series - An episode belonging to a set of related TV shows.
special - A content item that is not any of the above Media Types.
Deep Linking Content IDs may contain subIds which will result in various Deep Linking behaviors.
Many Roku channels will not require subIds.
SubIds are only required when Deep Linking to MRSS items,
however subIds may also be optionally used for other items.
When a subId is used in a Content ID,
it is separated from the DeepLinkId or Content UID by a bar or pipe character, as shown in these two example Content IDs:
item_0123|first ("item_0123" is a DeepLinkId, "first" is a subId)
6224222b-47fc-4e70-adae-16eb91e998fb|last ("6224222b-47fc-4e70-adae-16eb91e998fb" is a Content UID, "last" is a subId)
The following subId types are available:
bookmark - Play a bookmarked item.
first - Play the first item in a list.
last - Play the last item in a list.
none - Play a bookmarked item, overrides any series-list behavior.
{Position} - A number reprenting a position within a list. Play the item at the position in the list.
{Feed_DeepLinkId} - A DeepLinkId specified within an MRSS feed for a video within the feed. Play the item with this DeepLinkId from the MRSS feed.
To provide Roku with your sample Deep Linking information for testing and certification,
enter a video's Content UID or DeepLinkingId as the Content ID on the "Deep Linking" page in your Roku Developer Account.
The following screenshot is from the "Deep Linking" page of a Roku Developer Account:
Roku Developer Account - Deep Linking Test Content IDs using Instant TV Channel Content UIDs
Although Roku states that only individual video items may have Deep Linking Content IDs,
Instant TV Channel will correctly handle Content IDs for lists, grid rows, and MRSS lists.
List, grid row and MRSS Deep Linking Content IDs should be used with care,
as the Content ID will appear to Roku as the Content ID for a video,
and Roku requires that each video item must have a unique and unchanging Content ID.
Because lists and grid rows do not have a DeepLinkId parameter, the Content UID must be used for deep linking.
Content UIDs may be combined with subIds to deep link to individual items within a list.
The following table provides examples of how to combine DeepLinkIds and subIds to create Deep Linking Content IDs.
Many Roku channels will only need to use the basic Content ID Format shown in the 1st row of the table.
The DeepLinkId + subId combinations are only required when deep linking to MRSS items, although subIds may be used with other types of items as well.
If a DeepLinkId is blank or the parameter is missing,
then the item's Content UID is used as the DeepLinkId.
Example Deep Linking Content IDs and Behaviors (Unless Media Type is "season". See note #1 below.)
Content ID Format
Content Type
Behavior
Example Content ID
{DeepLinkId}
Video Item
Play the item starting at its bookmarked position. (See notes #2 and #3 below.)
movie_123 - DeepLinkId is the video's DeepLinkId value "movie_123".
Play the video with DeepLinkId "movie_123".
{DeepLinkId}
Horizontal, Vertical, Series, or MRSS List, or Grid Row
Play the bookmarked item from the list. (See notes #2 and #4 below.)
list_abc - DeepLinkId is the list's or row's DeepLinkId value "list_abc".
From the list with DeepLinkId "list_abc", play the bookmarked item.
{DeepLinkId}|bookmark
Any Item in a Horizontal, Vertical, or Series List, or Grid Row
Play the bookmarked item from the parent list of the item. (See note #4 below.)
movie_123|bookmark - DeepLinkId is the video's DeepLinkId value "movie_123" and subId is the exact text "bookmark".
From the parent list of the the video with DeepLinkId "movie_123", play the bookmarked item.
{DeepLinkId}|bookmark
Horizontal, Vertical, Series, or MRSS List, or Grid Row
Play the bookmarked item from the list. (See note #4 below.)
list_abc|bookmark - DeepLinkId is the list's or row's DeepLinkId value "list_abc" and subId is the exact text "bookmark".
From the list with DeepLinkId "list_abc", play the bookmarked item. This is the same as the Content ID of "list_abc|none".
{DeepLinkId}|first
Any Item in a Horizontal, Vertical, or Series List, or Grid Row
Play the first item in the parent list of the item.
movie_123|first - DeepLinkId is the video's DeepLinkId value "movie_123" and subId is the exact text "first".
From the parent list of the the video with DeepLinkId "movie_123", play the first item.
{DeepLinkId}|first
Horizontal, Vertical, Series, or MRSS List, or Grid Row
Play the first item in the list.
list_abc|first - DeepLinkId is the list's or row's DeepLinkId value "list_abc" and subId is the exact text "first".
From the list with DeepLinkId "list_abc", play the first item.
{DeepLinkId}|last
Any Item in a Horizontal, Vertical, or Series List, or Grid Row
Play the last item in the parent list of the item.
movie_123|last - DeepLinkId is the video's DeepLinkId value "movie_123" and subId is the exact text "last".
From the parent list of the the video with DeepLinkId "movie_123", play the last item.
{DeepLinkId}|last
Horizontal, Vertical, Series, or MRSS List, or Grid Row
Play the last item in the list.
list_abc|last - DeepLinkId is the list's or row's DeepLinkId value "list_abc" and subId is the exact text "last".
From the list with DeepLinkId "list_abc", play the last item.
{DeepLinkId}|none
Video Item
Play the item starting at its bookmarked position. (See note #3 below.)
movie_123|none - DeepLinkId is the video's DeepLinkId value "movie_123" and subId is the exact text "none".
Play the video with DeepLinkId "movie_123", even if the Media Type is "series".
{DeepLinkId}|none
Horizontal, Vertical, Series, or MRSS List, or Grid Row
Play the bookmarked item from the list. (See notes #2 and #3 below.)
list_abc|none - DeepLinkId is the list's or row's DeepLinkId value "list_123" and subId is the exact text "none".
From the list with DeepLinkId "list_abc", play the bookmarked item. This is the same as the Content ID "list_abc|bookmark".
{DeepLinkId}|{Position}
Any Item in a Horizontal, Vertical, or Series List, or Grid Row
Play the item at the position in the parent list of the item.
movie_123|5 - DeepLinkId is the video's DeepLinkId value "movie_123" and subId is the position "5".
From the parent list of the video with DeepLinkId "movie_123", play the 5th item.
{DeepLinkId}|{Position}
Horizontal, Vertical, Series, or MRSS List, or Grid Row
Play the item at the position within the list.
list_abc|5 - DeepLinkId is the list's or row's DeepLinkId value "list_abc" and subId is the position "5".
From the list with DeepLinkId "list_abc", play the 5th item.
{DeepLinkId}|{irc:deeplinkid}
MRSS List
Play the item in the MRSS list that has the specified irc:deeplinkid value.
mrss_xyz|movie_123 - DeepLinkId is the MRSS list's DeepLinkId value "mrss_xyz" and subId is the video's irc:deeplinkid value "movie_123".
The subId is the irc:deeplinkid value for a video within the MRSS XML feed.
From the MRSS list with DeepLinkId "mrss_xyz", play the video with irc:deeplinkid "movie_123".
Notes:
If Media Type is "season" then instead of immediately playing a video, the behavior will be to display the list containing the video with the provided Content ID. The viewer then selects an episode from the list.
If Media Type is "series" and no subId is appended to the contentID, then the Theme DeepLinkingSeriesBehavior parameter is used as the subId and the behavior will change to match the subId.
If a bookmark does not exist for a video, then the video is played from the beginning.
If a bookmark does not exist for a list, then the first item in the list is played starting at its bookmarked position.
Instant TV Channel is a cloud-based tool for Roku developers and content providers that shortens development time and eases maintenance after deployment.
