There are many different ways of linking a Roku channel with an online account. One of the easiest and fun is rendezvous style linking registration, developed by Roku developers to benefit the ARM developers. In rendezvous linking a channel displays a code to the user and asks them to use the computer to enter that code into a web site to complete the registration process.
Rendezvous linking is the typical flow and API used for registering and linking a device to an authentication service. The primary and recommended method for linking a device involves 3 main steps that combine to form rendezvous style linking.
The steps are as follows –
- The channel presents a short on-screen registration code on the Roku device.
- The user links the devices by inserting the registration code, provided on the provider’s website/service.
- After the code gets confirmed by the service to be correct then a token is issued to the Roku device. Once the token has been downloaded on the device, then a pop-up comes with congratulations message on the channel allowing the user to access the video service. Afterwards, everytime the channel gets launched the verification of the token takes place automatically.
In this way, rendezvous linking registration takes place for the user, entering the code, again and again, isn’t required. The Roku developers keep it simple for the users as well for the ARM developers.
How authentication flow?
Many activities between the device and the provider server perform the authentication. The steps are as follows:
- First, the Roku device sends a “pre-registration” request to the server.
- The server produces a short registration code and makes an entry in the database linking the code with the temporary request for linking.
- The Roku device receives the response made and shows the code to the user.
2. Device linking:
- The Roku device starts making a series of “link” requests to the server.
- The server replies to the link request with a “not completed” code till the user successfully enters the right and complete code into the website, or either the code expires.
3. Linking success:
- When the user successfully enters the code and other required credentials on the provider website, the server re-links the code with the user’s real account.
- Whenever the next time Roku device makes a “link” inquiry, the server acknowledges with a permanent code(token) that can be used to access the user’s account everytime the user requests.
Every subsequent API requests use this token to uniquely identify the user and the linked device. A request can be made anytime as HTTP GET with values in parameters, or HTTP POST with values in the body of the request, for example, like XML or JSON. Roku development team make it far too easy.
Step 1: Pre-registration
This step is used to recover the registration code from the server for device registration. The token is illustrated on the screen by the Roku device and the user is requested to go to the website and enter this token. It is advisable to make the code as short as possible in turn to make it easy for the end-user to enter, but assure the uniqueness during the retry period. The device should be registered at a particular frequency (retryInterval) during registration until the Roku device has been registered or the maximum time has expired (retryDuration).
Step 2: Device linking
This step is basically about keeping a check on the registration process, to examine whether the user is able to enter the code successfully on the provider’s website to link his/her Roku device. This particular step is about checking the status of the device at a specified time interval (retryInterval) from the point when pre-registration request was made until a successful response is received or either the maximum retry time (retryDuration) has passed. An example of the request/response is illustrated below in XML format:
Note: The device ID should not be used as the verification code as it is. But you can hash the device ID to generate an auth token as long as it provides a unique value each time.
The device linking request can fail because of various reasons, like:
- Missing or incorrect registration code
- Expired code
- The issues with the customer account (e.g. not registered, hold, etc.)
Step 3: Linking success
The final step after successful linking of the device is to send a token (rather an opaque string) back to the Roku device that will be written on the channel’s registry. This token can be used by the user/viewer to perform further desired operations on the server like play media or games and much more. Afterwards, everytime the channel is launched the service will match the token.
This token is the identifier for the account on the server, not the device serial number. This thing makes it easy for the user to unlink a device from an account just by removing that particular channel or she/he can simply factory reset the device which will also result in the token to be lost hence, unlinking the device.