Implementation

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

The 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. The API doesn't have a session concept and only stores a locking configuration that the user chose to set. It is entirely the responsibility of the client to track whether a session has been unlocked in current viewing session.

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 following the steps in PIN code verification

If the request succeeds then the client can allow the user to view any channel regardless of whether it is listed in their locked list.

The client should lock the channels again after some defined time period.

Fetching the configuration when the user logs in

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

GET /users/{user_id}/channel_lock_configuration

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:

{
  "data": {
    "type": "UserChannelLockingConfiguration",
  "account_channel_lock_status  "id": true,"da00a320-2bae-49af-9687-298ed3f01361",
    "attributes": {
      "sessionlock_channeladult_lock_statuschannels": true,
      "locked_channels": [
        "3bdb869c-4781-46f8-b00b-1a780664a7ab"
      ],
    }
  }
}

This indicates to the client that it should lock all adult channels, as well as the specific channel "3bdb869c-4781-46f8-b00b-1a780664a7ab"

Handling locked channels

Determining whether locking is enabled

The client should consider locking to be enabled when BOTH of the following conditions are true:

1. account_channel_lock_status is true, and
2. session_channel_lock_status is true

If either of these conditions is false then the client should consider all channels to be 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 is a list of the id's of channels that are blocked and an indication whether all adult channels must be blocked too.

Adult channels can be included in the locked list too, so when deciding if certain adult channel is to be displayed – consider both boolean flag and whether this channel is in the list. 

In short:

• Adult channel is locked if {{lock_adult_channels}} is true or this channel is in {{locked_channels}}
• Adult channel is unlocked only if {{lock_adult_channels}} is false and this channel is not in {{locked_channels}}
• Non-adult channel is locked if this channel is in {{locked_channels}}

Handling locked channels

The behaviour of the client towards locked channels 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:

themeDJango

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

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

PUTPATCH /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", "28ab9e8c-afad-40bc-a353-b6b6ddea9b9d", "05c722d2-d974-424a-acd6-3cd46cf06c8b"
  ]
}

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

{
  "accountlock_channeladult_lock_statuschannels": true,
  "session_channel_lock_status": true,
  "pin_code": "1234",
  "locked_channels": [
    "3bdb869c-4781-46f8-b00b-1a780664a7ab",     "1fd1a10c-53d0-49b1-ad1f-47a514c45b99"28ab9e8c-afad-40bc-a353-b6b6ddea9b9d", "05c722d2-d974-424a-acd6-3cd46cf06c8b", "89a9fa11-db05-4b72-b9fd-8f57d52196eb"
  ]
}

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", "28ab9e8c-afad-40bc-a353-b6b6ddea9b9d", "05c722d2-d974-424a-acd6-3cd46cf06c8b"
  ]
}

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:

is described in the PIN code change section