Developer Tutorial: Deep linking in Roku OS

Navigate directly to channel content by deep linking

Banner ads deep link initiator


On Roku devices, deep linking describes the process of launching channels and media content through an ad, a search result, or the My Feed feature. In order to support the global search interface and advertising initiatives, all Roku channels with indexed content are required to respond to deep link requests. The following guide details how to integrate deep linking on your Roku channel.

The primary sections are:

  1. How deep linking works in Roku OS
  2. Modifying a channel to support deep linking
  3. Testing deep linking

Deep linking use cases on Roku OS

Global Search

The Roku search directory provides a great example of how deep linking works.

Global Search

Search Results

As you enter your desired target content in the input field, you’ll be met by a list of all related results ranked by relevancy — movies, TV shows, actors, directors, channel names, games, and so forth.

Search Results

Utilizing Deep Linking

Once you find your desired content, you’ll see a list of all available channels from which it can be streamed. Selecting one of these options will launch a deep link directly to the intended content — namely, the series, season, or episode’s description page — as opposed to simply opening the channel’s main landing page. This dive straight into the description page is an example of deep linking at its finest.

Search results deep link initiator

Deep linking banner ads from the Roku home screen

Another common use case is advertisement. Channel developers can work with the Roku Audience Development team to craft banner ads that link directly to content within an application.

Banner ads deep link initiator

Banner advertisements leverage deep links to open the specified content in the channel. To explore this opportunity, visit

Modifying a channel to support deep linking

Accepting deep linking parameters in Main()

The first step is to modify the Main method to accept the deep linking parameters in BrightScript:

Function Main (args as Dynamic) as Void

Parsing deep linking parameters

Next, account for the different parameters that can be expected:

if (args.reason = “ad”) then
    if (args.AdID <> invalid) then
    end if
end if
  • Args.reason is a required parameter and states why the channel was launched.
  • Args.AdID is an optional parameter that is passed when the channel is launched from an ad. This parameter can be used to determine which ad launched the channel.
  • fireAdBeacon() is a function for any tracking beacons that need to be fired.
    • Note: This is a function that the developer has to write. It is not a Roku SDK function.

You must check if the user has access to the content:

if (user_validated() = true) then
end if

The user_validated() method determines if the user has signed up for the channel.

Required Parameters

For a full list of required parameters to support an ad or universal search, see our External Control Guide. ContentID and mediaType constitute the two parameters used most frequently.

When creating a deep link for content, two additional parameters must be set:

  • args.contentID and
  • args.MediaType
if (args.contentID <> invalid AND args.mediaType <> invalid) then
    do_deeplink(args.contentID, args.mediaType, screen)
end if

Once finished, don’t forget to initialize the home screen:


Note: It is also possible to deep link from one channel to another via the roUrlTransfer component and the launch command. See the External Control Protocol (ECP) documentation for more details.

User experience for deep linking

Developers need to consider the experience for Roku users when deep linking to different types of content such as episodes, movies, short-form, etc. For each different mediaType, a different deep linking behavior is required. The complete list can be found in our deep linking SDK documentation.

if (args.mediaType = “movie” )
    doSpringBoard(ContentID, Screen)
else if (args.mediaType = “short-form” or args.mediaType = “Live” or mediaType = “episode”) then
    playMedia(ContentID, Screen)
else if (args.mediaType = “series”)
    doEpisodicPicker(ContentID, Screen)
    Print “Unknown media type “, args.mediaType
end if

The user_validated() method determines if the user is entitled to have access to the content.

PlayMedia() takes a contentID and a screen and plays the media directly.

doEpisodicPicker() is used when a user selects a series or season and a provider (specifically, your channel). The contentID of the episode and season will be passed to your channel. Use that information to display the correct episode picker. This can easily be done by using the contentID to store multiple parameters.

contentID is a unique identifier for a specific piece of content. Since there is no predetermined format, you can have multiple parameters encoded in it (ex. “SeriesID | SeasonID | episodicID”). You can then parse the contentID for the following information:

Series_ID = myargs[0]
Season_code = myargs[1]

Testing deep linking

Deep linking can be tested by invoking the appropriate ECP command using command line tools such as cURL. By entering the curl command from the command line (terminal for mac users), you can launch the channel on the Roku device.

For deep linking purposes, you only need the IP address of your Roku device and the ContentID of the content where you’d like to deep link. A ChannelID may be needed if the channel is not previously installed on the Roku player.

Be aware that deep linking is triggered by an http post to port 8060 with the channelID and contentID.

Sample command to launch a Roku channel:

curl -d ‘’ “http://<roku-ip-address>:8060/launch/<channel_id>?contentID=<contentID>&mediaType=series”

Note: When deep linking to a channel, you must test to see if the channel is installed or not, otherwise the command will not launch.

Check and prompt install if channel is not on the Roku Device:

curl -d ‘’ “http://<roku-ip-address>:8060/install/<channel_id>?contentID=<contentID>&mediaType=series”

Related Resources:


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s