Customizing the appSchedule.json File

Terminology

The terms ‘programme', ‘program’ and ‘event' are used interchangeably in the following description and refer to the same thing.
The terms ‘enable’, ‘active’ and ‘displayed’ are used interchangeably in the following description and refer to the same thing.
The terms ‘disable’, 'deactivate’ and 'hidden’ are used interchangeably in the following description and refer to the same thing.

Background

The starter kit includes a special file called appSchedule.json. This file allows broadcasters to configure and schedule various applications on their services. Each broadcast station has its own unique appSchedule file which usually resides within each station folder.

For Station-1 in the default Starter kit, this file can be found at the following location:

/public/London/Station-1/schedule/appSchedule.json

The purpose of this appSchedule file is to offer a broadcaster control over which applications to enable or disable. Different applications can be activated or deactivated based on network-time or individual program-time (program boundary)
This gives broadcasters flexibility to configure various applications that can be displayed /activated or hidden /deactivated during specified time periods or during certain events.

The default appSchedule file for Station-1 looks like:

{
    "appSchedules": {
        "schedulePoll": 10,
        "graceTimeout": 20,
        "schedule": {
            "event1": {
                "start": 1654761240,
                "appName": "cta-ba",
                "properties": {
                }
            },
            "event2": {
                "start": 1655459340,
                "appName": "trigger-1",
                "properties": {
                }
            },
            "event3": {
                "start": 1655459340,
                "appName": "blank",
                "properties": {
                }
            }
        }
    }
}

Explanation of individual parameters

Let us now look at various properties that are defined and used within the appSchedule file.

"schedulePoll"
The default value of this property is set to 10 seconds for Station-1 application. This poll value is used in order to evaluate the source file (appSchedule.json file). This means that the framework will poll and check the source appSchedule.json file every 10 seconds and look for any changes in the contents of this file.

The framework accomplishes this by reading the contents of the file as well as by checking the CRC value.
If any changes are detected in the appSchedule.json file, the framework acts on these changes accordingly.

"start"
This property defines the start time of the application, i.e. the time at which a given application becomes active / enabled. The time format used for this property is UTC UNIX time.

“graceTimeout”

The purpose of graceTimeout period is to allow broadcasters to let users continue with their active session without a sudden change in the current session. In the example code for appSchedule.json shown above, graceTimeout is set to 20 seconds.

Grace time is only added before the start time of a given application listed in appScheule.json file provided that, at that point in time, the active application is other than the ones listed in appSchedule.json file.

Using the example code shown above, suppose the user is currently navigating through the Common application or watching a VOD event through the main (common application). Note that Common App is not listed in appSchedule.json file. At some point whilst watching a VOD event, user approaches the start time of the next application listed in appschedule.json file (event2). At this point in time, the grace period is added to the start time of the application which is due to become active now (i.e. event 2 will kick in at ‘start time of event 2 + graceTimeout’).

It should be noted that grace time is not added in cases where the current active application is from the list of applications mentioned in appsSchedule.json file. For example, if the user is currently watching Live TV and the current active application is the one listed under event1, then the application listed under event2 will kick in at ‘start time of event 2’.

"appName"
This property indicates the name of the application that the broadcaster wishes to enable / disable using appSchedule.json file.

"properties"
This property allows the broadcaster to override any default properties for the chosen application. The default properties for all applications are usually defined in the appsList.json file.

NOTE: A blank / placeholder application is now provided in the Starter kit and is defined in appsList.json file. It is a simple background application with no visualization. The purpose of this file is to allow broadcasters to introduce gaps in their appSchedule file.

How to use appSchedule file in real life scenarios

NOTE: The time format used for “start” and “end” is always Coordinated Universal Time (UTC) in UNIX format and in ‘second’ granularity.
In the following examples, we will use a 24-hour time window starting from 12:00:00AM to 11:59:59PM

Let us now discuss and elaborate on three main scenarios listed below:

Broadcaster wishes to hide the default trigger (and its associated main application) for a certain period
Broadcasters wishes to display a different trigger (and perhaps a different main application) at certain times of the day
Broadcaster wishes to display a different trigger (and perhaps a different main application) at the start of a particular program / event.

Scenario 1: Hide Trigger Application / Main Application

This option allows broadcasters to hide their trigger and any associated application for a certain duration during a 24-hour period. Let us assume that the broadcaster wishes to hide its default trigger (and any associated application) between 10:30 AM and 1:30 PM. In this case, the appSchedule file contents will look like:

{
    "appSchedules": {
        "schedulePoll": 10,
        "graceTimeout": 20,
        "schedule": {
            "event1": {
                "start": 1654761240,
                "appName": "trigger-1",
                "properties": {
                }
            },
            "event2": {
                "start": 1655458200,
                "appName": "blank",
                "properties": {
                }
            },
            "event3": {
                "start": 1655469000,
                "appName": "trigger-1",
                "properties": {
                }
            }
        }
    }
}

NOTES:

Note that the “start” time of event2 (blank application) will be 10:30 AM (converted into UNIX time)
Note that the “start” time of event3 (trigger-1) will be 13:30 (converted into UNIX time)

Scenario 1 Extension

If the broadcaster now wishes to repeat this pattern over several days during a given week or month, then there are two ways to accomplish this task:

a) Dynamically generate appSchedule file every day

The broadcaster can dynamically update the appSchedule file on the server. Depending on the polling period, the framework detects a change in the file and acts accordingly.

NOTE: This method requires the use of correct http cache headers in order to overcome any receiver caching issues.

b) Use date tag in bridge.json file

The broadcaster can insert date tag in the appSchedule entry of the bridge.json file. In this case, the appSchedule entry in Bridge.json will look like:

"bcastappSchedule": "/london/Station-1/schedule/appSchedule<date>.json",

In this case, the framework will replace the <date> tag with the corresponding value and include this in the URL. The broadcaster therefore needs to ensure that it has the correctly labelled appSchedule.json file available on the server.
This method also allows the broadcaster to create multiple appSchedule files in advance. Each appSchedule file can contain it own unique list of applications that need to be enabled / disabled.

NOTE: Our recommended method is to use this <date> tag approach as this approach automatically overcomes any receiver caching issues.

Scenario 2: Switch Trigger Application / Main application at certain times

This option allows broadcasters to replace or swap their default trigger application with a different trigger application (and any associated main application) for certain time window within a 24-hour period. Let us assume that the broadcaster wishes to swap trigger-1 application with trigger-3 application between 2:00 PM and 5:00 PM). In this case, the appSchedule file contents will look like:

{
    "appSchedules": {
        "schedulePoll": 10,
        "graceTimeout": 20,
        "schedule": {
            "event1": {
                "start": 1603792122,
                "appName": "trigger-1",
                "properties": {
                }
            },
            "event2": {
                "start": 1603792049,				
                "appName": "trigger-3",
                "properties": {
                }
            },
            "event3": {
                "start": 1603792069,
                "appName": "trigger-1",
                "properties": {
                }
            }			
        }
    }
}

As explained earlier in Scenario-1, if this pattern needs to be repeated over several days, then this can be achieved by using <date> tag method in bridge.json file.

Scenario 3: Swap Trigger Application / Main Application for a particular Event

This option allows broadcasters to replace their default trigger (and its associated main application) with a new trigger (and a new associated application) for a particular event. This could be useful in case of any national event like for example a soccer match starting and ending within a certain time-frame within a 24-hour period.

Let us assume that the broadcaster wishes to swap trigger-1 application with a soccer-trigger between 6:00 PM and 8:00 PM. This soccer trigger is associated with another (main) betting application which is overlaid on the screen showing various score cards. In this case, the appSchedule file contents will look like:

{
    "appSchedules": {
        "schedulePoll": 10,
        "graceTimeout": 300,
        "schedule": {
            "event1": {
                "start": 1603792122,
                "appName": "trigger-1",
                "properties": {
                }
            },
            "event2": {
                "start": 1603792055,				
                "appName": "soccer-trigger",
                "properties": {
                }
            },
            "event3": {
                "start": 1603792096,
                "appName": "trigger-1",
                "properties": {
                }
            }			
        }
    }
}

NOTE: In order to ensure that soccer-trigger invokes the betting app (and not the broadcaster’s default main application), the “linkApp” property should be correctly defined in the appsList.json file. This will ensure that the soccer-trigger will invoke the correct application.

UTC - UNIX Time Calculation Examples

A broadcaster situated in New York (East Coast) wishes to hide its default trigger-1 application for 2 hours between 2:00 PM and 4:00 PM on 30th May 2022.

As Eastern Standard time is 4 hours behind UTC, the broadcaster will need to take this time different into consideration. The UTC time when the trigger will be hidden for this broadcaster shall therefore be:

Between 10:00 AM and 12:00 PM (UTC)

A broadcaster situated in California (West Coast) wishes to hide its default trigger-1 application for 2 hours between 2:00 PM and 4:00 PM on 30th May 2022.

As Pacific time is 7 hours behind UTC, the broadcaster will need to take this time different into consideration. The UTC time when the trigger will be hidden for this broadcaster shall therefore be:

Between 07:00 AM and 09:00 AM (UTC)

IMPORTANT

Any change / update to appSchedule.json file is automatically reflected without the need for session refresh. If graceTimeout is applicable, then it will be added to the start time of the next event listed in appSchedule.json file.
There are currently no checks implemented in the framework to examine the “start” times defined for various events in appSchedule.json file. Any mismatch in these values could lead to framework wrongly interpreting appSchedule.json file.