How to implement Deep Linking in Roku SG application?

Question

I need help understanding deep linking, because our Roku Scene Graph application was rejected by Roku.

Roku explains deep linking here: https://sdkdocs.roku.com/display/sdkdoc/Deep+Linking, but this documentation is not detailing all information about deep linking. For example, how do we get the contentId and mediaType?

Here is our main() function that runs on launch:

function main(args as Dynamic) as Void
    print "args" args
    if (args.ContentId <> invalid) and (args.MediaType <> invalid)
        if (args.mediaType = "season")
            HomeScreen()
        end if 
    end if
end function

After the application launches, we print args, and we get this associative array. However this does not show any contentId and mediaType.

<Component: roAssociativeArray> =
{
    instant_on_run_mode: "foreground"
    lastExitOrTerminationReason: "EXIT_UNKNOWN"
    source: "auto-run-dev"
    splashTime: "1170"
}

Using this curl command, the application launches successfully showing the contentId and mediaType:

curl -d "" "http://10.1.1.114:8060/launch/dev?contentID=e59066f501310da32b54ec0b64319be0&MediaType=season"

Please help us and provide a better example to understand and implement easily Deep Linking.

Answer 1

You're on the right track. The purpose of the Deep Linking is to get a user from a Roku Search listing or banner directly to a season or episode of your channel.

There is not a great example in the docs of how you would program this for a Scene Graph channel, so we had to write this ourself also. Once you have it implemented there is a couple ways to test it:

1. Use the Eclipse plugin -> File > Export > BrightScript Deployment. Fill in the DeepLinking params field like so: contentID=1234&MediaType=episode

2. Use the Roku Deep Link Tester: http://devtools.web.roku.com/DeepLinkingTester/

3. Hard-code some deep link params into your channel

Here's how we implemented the Deep Linking logic in main.brs:

sub Main(args as Dynamic)

    screen = createObject("roSGScreen")
    m.port = createObject("roMessagePort")
    screen.setMessagePort(m.port)
    m.global = screen.getGlobalNode()

    'Deep Linking
    'args.ContentId = "78891" 'Testing only
    'args.MediaType = "episode" 'Testing only
    if (args.ContentId <> invalid) and (args.MediaType <> invalid)
        m.global.addField("DeepContentId", "string", true)
        m.global.addField("DeepMediaType", "string", true)

        m.global.DeepContentId = args.ContentId
        m.global.DeepMediaType = args.MediaType
    end if

    scene = screen.createScene("HomeScene")
    screen.show()

    '...load content, other startup logic

    while true
        msg = wait(0, m.port)
        msgType = type(msg)

        if msgType = "roSGScreenEvent"
            if msg.isScreenClosed() then exit while
        end if
    end while

    if screen <> invalid then
        screen.close()
        screen = invalid
    end if
end sub

Then on your home screen in HomeScene.brs, once your content has initialized:

'Check for deep link content
if m.global.DeepContentId <> invalid then

    if (m.global.DeepMediaType = "short form" or m.global.DeepMediaType = "movie" or m.global.DeepMediaType = "episode") then
        'find selected content in feed

        'play episode or movie content directly

    else if (m.global.DeepMediaType = "season")
        'find selected content in feed
        'show season screen for content
    else
        ? "Unrecognized Deep Link Media Type"
    end if
    'It may be necessary to remove deep link params
    m.global.DeepContentId = invalid
    m.global.DeepMediaType = invalid
end if

I hope this is helpful in getting your Deep Linking up and running. Let me know if I missed something.

Answer 2

Deep linking parameters are passed by firmware. You should only be able to handle them if they are passed. If no arguments are passed simply show home screen. If, for example, you have valid contentId in "args", you should find a content with such ID and play it once channel launches.