“Schedules”, objects that decide on the availability of objects associated with them, can either be created by editors or ingested.
Availability is decided on each request, with attributes of the request and of the requester factoring in, namely:
- Time of the request
- Language of the requester
- Locale (typically country) where the request originated
- Region to which the request’s origin belongs
- Device type from which the request was made (Android app, iOS app on iPhone, iOS app on iPad, web browser, Playstation 4 app …)
- Affiliate through which the requester logged in or is associated
- Type of the customer, which can be several or none at all, usable for arbitrary grouping of users
The values that these attribute can take are fully customizable and modifiable at any time.
In this diagram are:
- An article visible only on Android devices for English speakers from Dec 25th
- A season visible both on Android devices for English speakers from Dec 25th and also visible in France to anyone at anytime
- A set visible in France by anyone at anytime
Additionally, Schedules can be associated to objects as part of its membership of a set. The availability of an object as member of a set is therefore decided both by these schedules and those associated with the object itself.
In this image:
Brandonly available in South Korea
Brand, returning it only when queried by Korean speakers
- Make a TV Show only available to mobile devices
- Make movies available only to Sky subscribers. Make another batch of movies intersecting with the previous one available only to BBC subscribers. The intersection will be visible by both groups of clients.
- Target minority languages speakers: Display a film only in the Basque version of your website
- Easily manage complex distribution rights:
- Make two schedules managing rights agreed on with distributors:
- Available in France, Great Britain, Portugal for people speaking French and English, visiting on an Android device that connect via Sky, Canal + or MEO from March, 1st 2017 to June, 5th 2017
- Available in the United States and Japan, for people speaking French, English and Japanese, visiting on iPhone in 2018
- Assign them to brands and let Skylark clarify to whom they are available
Personalise your homepage: only show content available and relevant to the demographic of the current user
- Add a Schedule managing rights to Christmas movies: Active worldwide
- Create a Schedule targeting users for Christmas: Active in the western world from December 1st to December 31st
- Add the Christmas movies to the set managing your homepage, linked as members of the set to the Christmas Schedule
- During the month of December, the homepage of the mobile app of users in the western world shows these Christmas movies
- A/B testing by dividing the user base into groups and providing them with different content
Schedules are a descriptor of availability. They can be linked with a wide range of objects in Skylark. This is called “scheduling an object”, and objects that can be scheduled are called “schedulable”. An object can be scheduled with one or several Schedules. They describe its availability.
Schedules describe availability over multiple dimensions which contain all the possible states in which a client can be differentiated:
The availability is described as a subset of those dimensions:
As you can see in the figure above, two types of dimension are available in Skylark:
- Time, where values are ordered and continuous and can be targeted in ranges
- Discrete dimensions, where values have no relation to each other and must be targeted one by one
Here are the discrete dimensions on which Schedules are defined in Skylark.
Language: languages that users speak
Locale: countries (or other geographic areas) where the content is available
Region:region where the content is available (such asEMEA, North America, Cheshire…)
Device type: type of devices on which the content can be viewed
Affiliate: affiliate through which users can connect
Customer type: arbitrary set of groups that a customer can be part of
The discrete dimensions are fully customisable: they contain values customised to the needs of the product. This means, for instance, that a Skylark instance can start by supporting only English speaking visitors, and roll out other languages over time.
Schedules which have been ingested (called rights schedules) will have their rights attribute set to true, while the ones created in the CMS (called editorial schedules) will have their rights attribute set to false.
If no end date is specified on the timespan of a
Schedule, it is valid from its start date indefinitely.
Skylark filters lists of scheduled content wherever they are included in API responses: the response of a list endpoint and also lists of related objects.
In this section, the method to specify the schedule filter context of a request is presented. Then, the process of filtering based on this context is explained. A method to ask Skylark to bypass filtering is finally given.
As seen above, Schedules are subsets of dimensions representing the time of a request and other variables. The context of a request is also a subset of the same dimensions. When filtering, Skylark finds Schedules that match with the request’s context.
Specifying context is done by adding arguments to
GET requests. For instance the request represented in the diagram above is done by adding the following arguments:
Specifying subsets for the discrete dimensions is simple. All the values desired must be specified, separated by commas. Some Skylark installations will automatically infer some dimensions from the HTTP request, for example, by geolocating requests by IP.
Specifying time filters is explained in a later section.
Objects are examined one by one. When examining an object, its schedules are checked for a match against the context individually. An object needs at least one matching schedule to be included in the filtered list.
In the above diagram, the second object is included in the filtered list because it is linked to one matching schedule. Note that it is also linked to a non-matching one.
schedule to match against a request context, the
schedule must must match the context on a per dimension basis. There is always a match on a dimension when at least one of those two objects has no values specified. An object with no values specified on a dimension is considered as having no restrictions, and so matches the whole dimension.
The rules determining match of subsets on a dimension vary depending on the type of the dimension. For discrete dimensions, subsets match when they have at least one common value.
When matching time, the default behaviour is to match schedules that include the current time. Other schedules do not match.
Filtering is done on any list that is returned by Skylark, including Sets. However, the filtering process is slightly different for
Sets contain other objects, sometime schedulable objects. But it is also possible to schedule their membership of the
This is made possible by adding an intermediary object between the
Set and the contained object: the
ScheduledItems refer to a single object.
As indicated by their name,
ScheduledItems can be Scheduled. Items of a
Set are returned if both their
ScheduledItem containers and themselves match the request’s context.
Filtering by time isn’t available to general users. It is an administrative function that requires permissions to be granted to the user from their role.
First, let’s see how to specify a subset of the time dimension. It is possible to specify a timespan or a single date. This is done in two steps:
Specify a date with the keyword at on the request. If this step is ignored, at is set to the current time.
- Specify a second date with the until keyword. This specifies a range between at and until
- Specify when the desired content is scheduled relative to at with the keywords expired, current and future (their meaning is explained in the section below). They can be combined.
Then let’s see how the subsets on time dimensions are matched. It depends on how the context is defined. If the context is defined using current, expired and/or future, the dimensions matching are explained by the following diagram:
If the context is defined using until, schedules starting after at and ending before until will be matched.
Here are three keywords arguments for
GET request bypassing the normal filtering process. Again, these are only available to users with appropriate permissions.
|Returns all Objects|
|Returns all Objects not linked to any Schedule|
|Returns all Objects linked to the given Schedule(s)|
The following fields are added to the JSON representation of Schedulable objects:
schedule_urls: list the URL of all the schedules associated with the object
schedule_statuses: list the schedules associated with the object and whether they match the request context
It is possible to add these filters to all requests to Skylark. They take effect only when making requests for Schedulable objects. Please refer to the Technical Description for more information.
|Indicate the base date for the matching the time dimension. Defaults to the current time. ISO 8601 Timestamp|
|Establish a range between at and until for range-matching time. Default unset, to match a point in time.|
|Objects currently Scheduled are returned. Default to True|
|Objects scheduled in the past are returned. Default to False. Boolean|
|Objects scheduled currently or in the future are returned. Default to False. Boolean|
|Slugs of the language dimensions to match|
|Slugs of the locales to match|
|Slugs of the regions to match|
|Slugs of the device types to match|
|Slugs of the affiliates to match|
|Slugs of the customer types to match|
will filter a list of
Images whose schedules are valid for the
Affilliates bbc or cnn.
will return all
Episodes that have a
Schedule that has started but not ended, as well as any
episodes that have a
Schedule that will end in the future.
will return all
Sets that have a
Schedule which has ended and all Objects which have a
schedule that ends in the future.
The at keyword can be used together with the expired, current and future keywords, for example:
Both of the above calls return the same data, all the
Seasons that have a current
Schedule on 1st January 2000.
This will return all the
Seasons which have
Schedules ending after the 1st January, 2000