Implementation

In order to maintain performance AminoTV is careful not to provide client-specific API responses unless absolutely necessary.

When responding to requests for Channel (or related metadata) information the API will not take the account blocking status or the client blocking status into account.

The client should determine the user preferences and filter information out of the API response.

Unlocking channels for a session

The client should allow the user to specify that all channels should be unlocked for a particular viewing session.

This method of unlocking will enable all channels to be viewed for a limited period of time.

It is entirely the responsibility of the client to track whether a session has been unlocked in this manner.

If the user requests that their session be unlocked through the UI then the client should request that they input their PIN. 

The client can then verify that this PIN is correct by calling

PATCH /users/{user_id}/channel_lock_configuration

The request body should look something like this:

{
  "session_channel_lock_status": false,
  "pin_code": 1234,
}

Note:

• The API will verify the PIN code supplied against the one stored for the user account and return "403 Forbidden" if an incorrect PIN is supplied
• No other fields should be supplied; the API will respond with "400 Bad Request" if you try to PATCH the "locked_channels" at the same time as the session_channel_lock_status

Fetching the status when the user logs in

When the user logs in, the client should call the API to get the current status of channel locking on the account. 

This response can be cached for up to 10 minutes.

AminoTV does not currently implement a "push" service to notify clients of updates and therefore the client should periodically refresh the account locking status.

The response will look something like this:

{
  "locked_channels": [
    "3bdb869c-4781-46f8-b00b-1a780664a7ab", "28ab9e8c-afad-40bc-a353-b6b6ddea9b9d", "05c722d2-d974-424a-acd6-3cd46cf06c8b"
  ]
}

This is a list of the id's of channels that are blocked.

Handling locked channels

Determining whether locking is enabled

The client should consider locking to be enabled when the channel appears in the list of id's in the "locked_channels" key.

The client is responsible for managing whether a viewing session is unlocked

Determining which channels are locked

Assuming that locking is enabled the client should consider a channel to be locked if EITHER of the following conditions are true:

1. The channel is flagged as being adult rated
2. The channel id appears in the array of locked channels

What to do if a channel is locked

This will largely be determined by the customer specification, but broadly we expect the following to occur in the frontend:

• Some indication is shown to the user that the content item is locked
• The user is prevented from seeing details of the content item
• Thumbnails for the content are replaced with a placeholder that is suitable for general audiences
• The user is prevented from playing the content

It is the responsibility of the client to perform this filtering;  In order to improve performance the API server will not provide user specific responses.

First time usage

Step 1: Enable or disable channel locking on the account

By default adult channels will be blocked and the account holder will need to unlock them.

Initially, the account will have a default PIN code set on it.

The client should ask the user if the account should have channel locking enabled or not and then call

PUT /users/{user_id}/channel_lock_configuration

to specify whether the `account_channel_lock_status` should be set or not.

If the "account_channel_lock_status" key of the request body is set to false then adult channels will be unblocked.

For example, the following request body would disable channel blocking entirely across the account:

{
  "account_channel_lock_status": false,
  "session_channel_lock_status": false,
  "pin_code": "1234",
  "locked_channels": []
}

Step 2: Change the PIN code

If the user decides to leave channel blocking enabled then the client should prompt the user to change their PIN code.

Once the client has obtained the new PIN code from the user it should call

PUT /users/{user_id}/channel_lock_configuration

in order to change the value.

The current PIN code must be supplied in order to validate the request.

Locking or unlocking adult channels

Account wide setting

If the user wants to allow adult channels to be played without the need for any authorization they are able to disable channel locking on the account.

This setting will affect all devices and persist over multiple login sessions.  In other words, if the user logs out on one device and then logs in on another then they will still be able to play adult channels.

In order to set the status of channel locking for the account the client should call

PUT /users/{user_id}/channel_lock_configuration

to specify whether the `account_channel_lock_status` should be set or not.  If the "account_channel_lock_status" key of the request body is set to false then adult channels will be unblocked.

Per viewing session setting

The user is able to temporarily disable channel blocking and allow adult channels to be displayed. 

This will allow them to watch adult channels on their current device for the duration of their viewing session.

In order to do this, the client should:

1. Call PUT /users/{user_id}/channel_lock_configuration and set "session_channel_lock_status" to false
2. Locally store the time at which the PIN code was authenticated
3. Allow the user to view adult content for the time window specified by the operator

Locking and unlocking arbitrary channels

The user is able to lock any channel, regardless of its adult rating status.

To change the list of channels that are currently locked the client should call

PUT /users/{user_id}/channel_lock_configuration

and set the array of locked channels to the desired list.

For example, lets say that the the response to the request that obtained the initial status was:

{
  "account_channel_lock_status": true,
  "session_channel_lock_status": true,
  "locked_channels": [
    "3bdb869c-4781-46f8-b00b-1a780664a7ab"
  ]
}

In order to add a new channel to the list the client would use the following request body:

{
  "account_channel_lock_status": true,
  "session_channel_lock_status": true,
  "pin_code": "1234",
  "locked_channels": [
    "3bdb869c-4781-46f8-b00b-1a780664a7ab",
    "1fd1a10c-53d0-49b1-ad1f-47a514c45b99"
  ]
}

And to remove that same channel and restore the list to how it was originally the following request body would be used:

{
  "account_channel_lock_status": true,
  "session_channel_lock_status": true,
  "pin_code": "1234",
  "locked_channels": [
    "3bdb869c-4781-46f8-b00b-1a780664a7ab"
  ]
}

Note that in both cases when the client makes a change to the entity it is required to provide the valid PIN code

Managing the PIN code

The user may want to change their PIN code.  To facilitate this the client needs to create a request to

PUT /users/{user_id}/channel_lock_configuration

The new PIN code should be supplied in the "new_pin_code" field. 

The API will respond with "400 Bad Request" if the PIN code does not meet the following validation requirements:

• Numeric
• Greater than zero
• Number of digits must be exactly 4
• May not be the same as the current code

An example of the PUT request body is as follows:

{
  "account_channel_lock_status": true,
  "session_channel_lock_status": true,
  "pin_code": 1234,
  "new_pin_code": 1234,
  "locked_channels": [
    "3bdb869c-4781-46f8-b00b-1a780664a7ab"
  ]
}