Introduction

In some countries there are local television channels that need to be made available to people living within a particular locality.

Operators are required to:

1. Make local channels available to local residents
2. Ensure that local channels from other areas are not available

Visibility of local channels

Unlike national channels, you should hide local channels that the user is not licensed to watch. 

This table summarizes how you should work with local channels in the frontend.

Type of channel	Display in UI for authenticated user	Display in UI for guest user
National channel
Local channel for the area that the user lives in	If licensed
Local channel for the area that the user does not live in

Amino implementation

Amino models local channels by including a boolean flag that indicates whether the channel is local or not.

Users are licensed by the customer to view particular local channels;  Amino does not store information about where the user lives and cannot determine what channels they need to be able to view.

Therefore, when displaying a list of local channels to a user, the client should:

1. Obtain a general list of channels and find the ones which are local by examining the flag
2. Filter out local channels from this list that the user does not have a license for

Use case examples

Determining what channels to display to an authenticated user

With the legacy endpoints

Call the API documented at Channel#/Channel/indexUserSpecificChannels

Display all national channels that have a value of "false" in the "isLocal" field

Display local channels matching both of the following condition:

1. Have a value of "true" in the "isUserAuthorized" field
2. Have a value of "true" in the "isLocal" field

With the REST based endpoints

See "what channels should I display to the user" at /wiki/spaces/MAPI/pages/49676405

Getting a list of local channels

With the legacy endpoints

Our legacy endpoint is user specific and performs the license checks required.

The API is documented at Channel#/Channel/indexUserSpecificChannels

We use the "isUserAuthorized" field to indicate whether the user has license to the channel or not.

We use the "isLocal" field to indicate whether a channel is local channel.

Therefore, in order to get a list of the local channels the client should:

1. Call the GET method on the index of user specific channels
   
2. Iterate through the list and remove any channel match both of the following condition:
   1. Have a value of "true" in the "isLocal" field
   2. Have a value of "false" in the "isUserAuthorized" field

With the REST based endpoints

The REST based API has not yet been released.

Step 1 - Obtain a list of channels

Fetch an index of the Channel resource.  This API is documented at Metadata: Channels#/Channels/GetChannelIndex

Note that this endpoint is not filtered for the individual user in order to make it publicly cacheable and reduce load on the API.

Step 2 - Filter out channels

The frontend should filter out channels by removing:

• Channels whose availability window does not include the current time
  • See Channel.availability_window.time_limited_event
  • If this field is true then compare the current time to the "not before" and "not after" definitions
• Demo channels, unless the user is a demo user
• Channels that are geo-blocked for the user if this is required by customer
• Channels that do not have the local flag or "is_local_channel" = false

This is documented in detail here and only the last bullet point is different from the general approach to managing channels.

Step 3 - Obtain the user licenses

Fetch the channel licenses that are related to a user by calling the API documented at License

Step 4 - Remove local channels that the user has no license for

Please see the documentation on Channels at /wiki/spaces/MAPI/pages/49676405