Skip to end of metadata
Go to start of metadata


This document describes an example set of API's for registering and linking a device to a video service using a code based or "rendezvous" style of registration. This type of registration presents the user with a short on-screen code during setup. The user then enters this code into the provider website to establish a linkage between the device and the user account. Once the device detects that registration is complete, it displays a congratulations screen and allows the user access to the video service.

Several transactions between the device and the provider server make this work.  First, the device makes a "pre-registration" request to the server.  The server generates a short registration code and sets up an entry in a database associating the code with a temporary request for linking.  The device receives this response and displays the code to the user. It then begins making a sequence of "link" requests to the server.  The server responds to the link request with a "not completed" code until the user successfully enters the code into the web site, or the code expires.  When the user has successfully entered the code plus any other necessary credentials on the provider web site, the server reassociates the code with the user's real account.  Then the next time the device makes a "link" query, the server responds with a permanent token that can be used to access the user's account.  All subsequent API requests use this token to uniquely identify the customer and device.

A request can be made as HTTP GET with values in parameters, or HTTP POST with values in the body of the request, for example, as XML.

Pre-Registration 

 

This transaction is used to retrieve a registration code from the server for device registration.  The code is displayed on screen by the device and the user is requested to go to the website and enter this code.  It is desirable to make the code as short as possible to make it easy for the user to enter, yet ensure uniqueness during the retry interval.  The device will poll at a specified frequency (retryInterval) during registration until the device has been registered or the maximum time has expired (retryDuration). 


Pre-registration Request

<preRegistration>
<deviceID> (unique id/serial number for the device) </deviceID>
<deviceTypeID> (optional opaque string identifying device type) </deviceTypeID>
<firmwareVersion> (optional major.minor.build) </firmwareVersion>
</preRegistration>

Response

<result>
<status> success/failure </status>
<regCode> (small ~5 character code customer will enter onto web site) </regCode>
<retryInterval> (polling interval in secs to detect completion (e.g. 30) </retryInterval>
<retryDuration> (max duration in secs for retries (e.g. 900) ) </retryDuration>
</result>

Device Linking


This transaction is used to check the registration progress to see if the user has successfully entered their registration code on the website to link their device. This method is polled continuously at the specified interval (retryInterval) from the time the preregistration request is made until a success response is received or until the max retry time (retryDuration) has elapsed.


Link Request

<linkAccount>
<regCode> (current registration code from PreRegistration request) </regCode>
<deviceID> (unique id/serial number for the device) </deviceID>
<deviceTypeID> (opaque string identifying device type) </deviceTypeID>
</linkAccount>

Intermediate Response
<result>
<status> incomplete </status>
</result>

Final Response

<result>
<status> success/failure </status>
<deviceToken> (opaque string to identify account for future requests) </deviceToken>
<customerId> (optional customer ID if required by partner) </customerId>
<creationTime> (optional ISO8601 date/time value) </creationTime>
</result>

 

The device linking request may fail for several reasons, such as:

Missing or invalid registration code
Expired registration code
Customer account issue (e.g. not registered, hold, etc.)

The deviceToken can then be used by the client to perform further operations on the server, such as play media.  This token, and not the device serial number, should be used to identify an account on the server.  This allows a user to disassociate a device from an account (unlink) by simply removing the channel which causes the stored device token to be discarded.

 

  • No labels