Skip to content

Latest commit

 

History

History
195 lines (155 loc) · 10.8 KB

deep-linking.md

File metadata and controls

195 lines (155 loc) · 10.8 KB

Developer Tutorial — Deep linking in Roku OS

Navigate directly to channel content by deep linking

Banner ads deep link initiator

Overview for the platform

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 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.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

do_validate_flow(screen)



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

Required Parameters

The following parameters are required to support ads or universal search:

Parameter Description Example
contentID Partner-defined unique identifier for a specific piece of content contentID=12345, and so forth
mediaType Parameter to give context to the type of contentID passed "series," "episode," "movie," "shortform," and "live"

 

The parameters "track" and "playlist" can also be used for music. Roku does not intend on supporting those in the OS, but you could extract them from an Ad.
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:

    do_Homescreen(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.

To pass channel certification, developers are required to implement episode selection screens (aka “episodic pickers”) when deep linking to a series.

Specifically, here are the main guidelines to follow:

    • Series: When deep linking to a series, there must be a episode selection screen (“episode picker”) for easily selecting a specific episode in addition to the main item in focus.
    • Episodes: When deep linking into a specific episode, it’s important to provide a springboard experience that includes an episode picker for different episodes. The behavior should keep the selected episode in focus with details while providing an ability to select other episodes within that view.
    • Movies: There are two main ways a deep link should respond:
      • When a movie has been purchased previously or is free: the content should play automatically.
      • If a purchase is required to watch: a purchase screen or a “Buy Now” option on a springboard should be presented prior to playback.
    • Short form: Content should play automatically.
    • Live: Content should play automatically.
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
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:

Myargs=args.ContentID.split(“|”)

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: