Roku Deep Linking


This Instant TV Channel Help article is applicable to Custom SDK Roku channels. The DeepLinkId parameter mentioned in this Help article is only available in new video items created in channels at Update #465 or later. The equivalent of the DeepLinkId for an item created prior to Update #465 is the item's 36-character Content UID which is displayed under the item's poster artwork in the upper-right window of the Content page.

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 the contentIds and mediaTypes into the "Test Accounts & Deep Linking Parameters" section of the "Support Information" page in your Roku Developer Account. The following screenshots are from the "Support Information" page of a Roku Developer Account:


Roku Developer Account - Deep Linking Test contentIds using DeepLinkIds


Roku Developer Account - Deep Linking Test contentIds using 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:
  1. 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.
  2. 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.
  3. If a bookmark does not exist for a video, then the video is played from the beginning.
  4. If a bookmark does not exist for a list, then the first item in the list is played starting at its bookmarked position.

You may test Deep Linking with your channel by using the official Roku Deep Linking tool: https://my.roku.com/account/add?channel=KX3UPK

The command-line tool "cURL" may also be used for testing: https://sdkdocs.roku.com/display/sdkdoc/Deep+Linking#DeepLinking-UsingcURLfortesting.

The Roku Developer Website has additional information about Deep Linking.



Instant TV Channel is a cloud-based tool for Roku developers and content providers that shortens development time and eases maintenance after deployment.



Access Code: U463
Check out Instant TV Channel by adding our latest demonstration channel to your Roku player, or watch the YouTube video.

Need help with your Roku?

We are unable to provide technical support for your Roku device.

Please visit www.roku.com for assistance.



Instant TV Channel is not affiliated with nor endorsed by Roku Inc.