Overview
OpenTV Video Platform allows you to enable in-home detection for open devices. The way this works is as follows:
-
Once the managed device (STB) has successfully authenticated, it calls a special IAS endpoint to get the accountID and tenant ID in encrypted form.
-
The STB now periodically broadcasts this encrypted account ID / tenant ID on the home network.
-
The client application running on an open device must listen for this broadcast token and retain it once it has received it.
-
When the client application running on an open device signs in, performs a token refresh, or detects a change in connection type, it must call another IAS endpoint, passing the token its in-home status (true or false).
-
IAS will decrypt the token and verify that the account ID and tenant ID are the same as those in the access token. If so, it sets in-home to true in the updated access token that it returns to the client. The client must use this updated token for all subsequent calls to the platform.
-
When the client application calls MDS to get content, channels, and so on, MDS checks whether in-home is set to true in the token that the app passes as part of its request and filters the content as appropriate (that is, if in-home is false, it filters out the content/channels that can only be consumed in-home).
Prerequisites
In-home detection must be enabled – see:
The in-home flag must be set for the content and channels that require it. See:
-
Channels – Manage channel features
-
Content – Editing Editorial information
STB – getting the encrypted account ID and tenant ID
Request
To get the the encrypted account ID and tenant ID, the client app running on the STB makes a GET request to:
https://<host>:<port>/ias/v3/token/actions/generateUpdateInHomeToken
Mandatory arguments
-
Authorization– the access token generated during sign-on (in header)
Other arguments
None
Response
A successful request will return an HTTP 200 status. The response includes the token that the STB will broadcast on the local network.
If the Authorization (access) token is missing or if the account ID or tenant ID is missing, the request will return an HTTP 400 status.
Client app on open device – updating in-home status
Request
After signing in, refreshing its access and refresh tokens, and after detecting a change in network type (for example, from WiFi to cellular), the client app on an open device must update its in-home status. It does this by making a PUT request to:
https://<host>:<port>/ias/v3/token/actions/updateInHomeStatus
It is very important that after detecting a change in network type (for example, from WiFi to cellular), the client app on an open device updates its in-home status.
If the client app determines that it is not connected to its home network when signing in, it does not need to make this request. In all other cases, it does need to make this request.
If the client moves from in-home to out of home or vice-versa, it should refresh any metadata that this could effect (for example, channels lists).
Mandatory arguments
-
Authorization– the access token generated during sign-on (in header) -
updateInHomeToken– the token that was broadcast by the STB (in body) -
inHome– whether the device is on the home network (true) or not (false)
Note that when the client detects that the connection type has changed and it is no longer receiving the broadcast token from the STB, it must setinHometofalsewhen making this request.
Other arguments
None
Example
A request with a body like this will update the app’s in-home status to true:
{
"updateInHomeToken": "0cd85e3b59367f865a1a08c4b5314e",
"inHome": true
}
Response
A successful request will return an HTTP 200 status. The response includes the updated access token, which includes the correctly-set in-home flag. The app must use this access token in all subsequent calls to the platform.
An invalid request will return an HTTP 400 status (see the IAS API documentation for details).
Example
A successful request will return a response in the following form:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiIzMjE1MTYiLCJhbGciOiJIUzI1NiJ9.eyJ0eXAiOiJEZXZBdXRoTiIsImFjY291bnRQcm9maWxlSWQiOiJERUZBVUxUIiwiZXhwIjoxNzM2MjM5MTU3LCJkZXZpY2VJZCI6IlNURUZfREVWX1BVQl8zIiwidGVuYW50SWQiOiJuYWdyYSIsImFjY291bnRJZCI6IlNURUZfQUNDXzMiLCJvbk5ldHdvcmsiOnRydWUsImRldmljZVByb2ZpbGVJZCI6IkRFRkFVTFQiLCJzZXNzaW9uQ29udHJvbCI6eyJtYXhTZXNzaW9ucyI6Mywic2Vzc2lvbkNvbnRyb2xFbmFibGVkIjp0cnVlfSwiYmxvY2tpbmdJbmZvcm1hdGlvbiI6e30sImNhY2hlS2V5IjoiUkVWR1FWVk1WQSIsImZpbHRlcmluZ0luZm9ybWF0aW9uIjp7fSwiaW5Ib21lIjp0cnVlLCJmaXhlZF9leHAiOjE3OTkzMDc1NjksInZlciI6IjEuMCIsImdlb0Jsb2NrRXhlbXB0Ijp0cnVlLCJiaWxsaW5nQ291bnRyeUNvZGUiOiJFbXB0eUNvdW50cnkifQ.f7QLeHJPAZpOBUGHMUNERY7nTn_jbcE3E8v-SngAydQ"
}