Navigate directly to channel content by deep linking
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:
- How deep linking works in Roku OS
- Modifying a channel to support deep linking
- Testing deep linking
Deep linking use cases on Roku OS
The Roku search directory provides a great example of how deep linking works.
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.
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.
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 advertisements leverage deep links to open the specified content in the channel. To explore this opportunity, visit roku.com/advertising.
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 fireAdBeacon(args.AdID) else fireAdBeacon(“unspecified”) end if end if
Args.reasonis a required parameter and states why the channel was launched.
Args.AdIDis 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 do_validate_flow(screen) end if
user_validated() method determines if the user has signed up for the channel.
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:
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:
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) else Print “Unknown media type “, args.mediaType end if
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:
Myargs=args.ContentID.split(“|”) Series_ID = myargs Season_code = myargs
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”
- Deep Linking Documentation: https://sdkdocs.roku.com/display/sdkdoc/Deep+Linking
- RAF Framework: blog.roku.com/developer/2016/02/10/roku-ad-framework/
- Billing Services: blog.roku.com/developer/2016/04/07/roku-billing-services/
- External Control Protocol: sdkdocs.roku.com/display/sdkdoc/External+Control+Guide#ExternalControlGuide-ImplementingDeepLinkinginaChannel
- How search works: sdkdocs.roku.com/display/sdkdoc/Roku+Search