Enabling in-home detection for open devices

Overview

OpenTV Video Platform allows you to enable in-home detection for open devices. The way this works is as follows:

1. Once the managed device (STB) has successfully authenticated, it calls a special IAS endpoint, generateUpdateInHomeToken, to get the account ID and tenant ID in encrypted form.

2. The STB now periodically broadcasts this encrypted string on the home network.

3. The client application running on an open device must listen for this broadcast string.

4. 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 the IAS updateInHomeStatus endpoint, passing it the encrypted string that it received from the STB.

5. 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. If not, it sets in-home to false in the token it returns.
   The client must use this updated token for all subsequent calls to the platform.

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

See Use cases, below, for details of how this works in various scenarios.

Prerequisites

In-home detection must be enabled – see:

• Network Settings

• Account profiles

The in-home flag must be set for the content and channels that require it. See:

• Channels – Manage channel features

• Content – Editing Editorial information

Use cases

Client app is used in the account holder’s home

1. At start-up, the STB calls generateUpdateInHomeToken to get the encrypted string.

2. The STB periodically broadcasts the encrypted string.

3. The client app listens for and receives the encrypted string.

4. The client app signs on and gets an access token.

5. The client app calls updateInHomeStatus, passing in the encrypted string.

6. IAS decrypts the string and compares the account ID and tenant ID with the values for the account.
   As the IDs match in this case, it returns an updated access token, with inHome set to true.

7. The client app can play back channels and content that are in-home restricted.

Client app is use in somebody else’s home

This assumes that this home also belongs to a subscriber to the service.

1. At start-up, the STB calls generateUpdateInHomeToken to get the encrypted string.

2. The STB periodically broadcasts the encrypted string.

3. The client app listens for and receives the encrypted string.

4. The client app signs on and gets an access token.

5. The client app calls updateInHomeStatus, passing in the encrypted string.

6. IAS decrypts the string and compares the account ID and tenant ID with the values for the account.
   As the IDs do not match in this case, it returns an updated access token, with inHome set to false.

7. The client app cannot play back channels and content that are in-home restricted.

Client app leaves the account holder’s home

1. At start-up, the STB calls generateUpdateInHomeToken to get the encrypted string.

2. The STB periodically broadcasts the encrypted string.

3. The client app listens for and receives the encrypted string.

4. The client app signs on and gets an access token.

5. The client app calls updateInHomeStatus, passing in the encrypted string.

6. IAS decrypts the string and compares the account ID and tenant ID with the values for the account.
   As the IDs match in this case, it returns an updated access token, with inHome set to true.

7. The client app can play back channels and content that are in-home restricted.

8. The device running the client app leaves the account holder’s home.

9. The client app detects the network change and calls refresh.

10. IAS returns an access token with inHome set to false.

11. The client app now cannot play back channels and content that are in-home restricted.

Client app returns to the account holder’s home having previously left

This use case assumes that the client app left the account holder’s home as described in the previous use case, above.

1. The device running the client app enters the account holder’s home and connects automatically to the wifi.

2. The client app detects the network change and calls refresh.

3. IAS returns an access token with inHome set to false.

4. The client app listens for and receives the encrypted string.

5. The client app calls updateInHomeStatus, passing in the encrypted string.

6. IAS decrypts the string and compares the account ID and tenant ID with the values for the account.
   As the IDs match in this case, it returns an updated access token, with inHome set to true.

7. The client app can play back channels and content that are in-home restricted.

API endpoints

generateUpdateInHomeToken

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.

updateInHomeStatus

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, or from one wifi network to another), the client app on an open device updates its in-home status.

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

When the client moves from out of home to in-home, after detecting the network change, it must wait until it receives the encrypted string before calling the updateInHomeStatus endpoint. This is because the STB does not broadcast the string continuously.

Mandatory arguments

• Authorization – the access token generated during sign-on (in header)

• updateInHomeToken – the token that was broadcast by the STB (in body)

Other arguments

None

Example

A request with a body like this will update the app’s in-home status:

{
  "updateInHomeToken": "0cd85e3b59367f865a1a08c4b5314e"
}

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"
}

See also

Identity Authentication Service (IAS) API documentation