Roku requires that you provide an example Deep Linking contentId for each mediaType in your SDK channel when you submit the channel for approval.
Deep Linking allows your channel's content to be directly accessed from outside of the channel, for example from a banner ad on the Roku home screen.
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 contentId 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 contentId:
Each Deep Linking contentId must be assigned a mediaType when submitted to Roku.
The following mediaTypes are accepted by Roku:
movie - A long-form film or movie.
short-form - 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 mediaTypes.
Deep Linking contentIds 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 contentID,
it is separated from the DeepLinkId or Content UID by a bar or pipe character, as shown in these two example contentIds:
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 contentIds,
Instant TV Channel will correctly handle contentIds for lists, grid rows, and MRSS lists.
List, grid row and MRSS Deep Linking contentIds should be used with care,
as the contentId will appear to Roku as the contentId for a video,
and Roku requires that each video item must have a unique and unchanging contentId.
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 contentIds.
Many Roku channels will only need to use the basic contentId 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 contentIds and Behaviors (Unless mediaType is "season". See note #1 below.)
contentId Format
Content Type
Behavior
Example contentId
{DeepLinkId}
Video Item
Play the item starting at its bookmarked position. (See notes #2 and #3 below.)
movie_123 - DeepLinkId is "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 "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 "movie_123" and subId is "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 "list_abc" and subId is "bookmark". From the list with DeepLinkId "list_abc", play the bookmarked item. This is the same as the contentId 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 "movie_123" and subId is "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 "list_abc" and subId is "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 "movie_123" and subId is "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 "list_abc" and subId is "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 "movie_123" and subId is "none". Play the video with DeepLinkId "movie_123", even if the mediaType 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 "list_123" and subId is "none". From the list with DeepLinkId "list_abc", play the bookmarked item. This is the same as the contentId "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 "movie_123" and subId is "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 "list_abc" and subId is "5". From the list with DeepLinkId "list_abc", play the 5th item.
{DeepLinkId}|{Feed_DeepLinkId}
MRSS List
Play the item in the MRSS list that has the specified feed DeepLinkId.
mrss_xyz|movie_123 - DeepLinkId is "mrss_xyz" and subId is "movie_123". The subId is a DeepLinkId specified for a video within the MRSS XML feed. From the MRSS list with DeepLinkId "mrss_xyz", play the video with DeepLinkId "movie_123".
Notes:
If mediaType is "season" then instead of immediately playing a video, the behavior will be to display the list containing the video with the provided contentId. The viewer then selects an episode from the list.
If mediaType 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.
