Introduction

v23 was originally planned as a short internal release focusing primarily on technical debt. We also planned to prepare for moving onto shorter release cycles and ultimately continuous delivery, which would entail some breaking changes in v23, so that we could provide backwards compatibility in subsequent releases. As a result v23 is heavily biased towards how things work under the hood rather than Producer-facing features.

In the course of v23 development our priorities shifted back to v22, which meant v23 took longer than originally planned. We've extended v22 with new features, such as Instagram voting, Control API rate limits, listings limits, multi vote GNIP voting, GNIP voting restrictions on number of followers, collection items reordering, collection items labelling, and performance improvements. All of these features were ported into v23 as well.

You will also find that we've made several breaking changes, which was done intentionally. We have made the foundations more consistent and flexible to enable more efficient development in the future. Most of these changes are around APIs, including Control API, LViS Service API, Leaderboard API and client APIs. Although breaking changes where made, it should not take longer than a couple of days to migrate. Please refer to our migration guide.

The biggest change in the APIs is that we are moving away from using numerical IDs for objects in favour of UUIDs. In v22 some of the APIs used numerical IDs and some used UUIDs, which made it impossible or very cumbersome in some cases to integrate several different APIs. For example LViS Service notifications used UUIDs, but Control API used numerical IDs, so making Control API calls off the back of receiving a notification was a problem. In v23 we've replaced the double ID system with a single system of using UUIDs.

The second biggest change, closely linked to the first, is replacing Control API v1 with v2, where v2 uses UUIDs to identify objects and also significantly changes the way to fetch a list of events.

Control API v1

Control API v1 has been removed. We've decided to remove it rather than deprecate because the scope in which v1 would be usable became very narrow after we migrated other APIs to use UUIDs as their main object ID mechanism. V1 also had high potential for putting heavy load on the system due to lack of filtering facility.

Control API v2

V2 uses UUIDs as object identifiers, introduces a more flexible and safer way of fetching events, implements a consistent approach around actions and element states, has enhanced image properties validations, and adds functionality for apps and accounts management. Full documentation is here.

UUID

As an example:

• In v22: PATCH /api/v1/elements/123

• In v23: PATCH /api/v2/elements/f6844ce1-28a5-478f-9f71-d60112b2944a

Element actions

Actions include publish, stop, results reveal. In Control API v1 there was a mix of approaches, some actions required the action attribute, others did not and worked as a side effect of setting a state property to a desired state. In v2 this side effect based approach is removed and the explicit action attribute is used to:

• publish an element (added in v2)

• stop an active element (available in v1)

• reveal correct answer (available in v1)

• reveal results (available in v1)

• revoke an element (added in v2)

Please see documentation and example.

Element states

Element states exposed by Control API v2 are more granular and better reflect the life cycle of an element in v23: "non_scheduled", "future", "current, "past", "on_demand", "revoked", "cancelled", against these in v22: "nonscheduled", "scheduled", "current", "finished", "revoked", "cancelled".

All of these states and their combinations can be used for filtering when fetching a list of elements.

Please see element states documentation.

Fetching events

Events fetching in v22 was limited and a heavy “all or nothing” operation. V23 is much more flexible. Fetching can be fine-tuned to a particular need via filtering and sorting. The results are not returned as one bulk either. Instead you can fetch them using a cursor page by page.

Sorting

GET /events supports sorting by start time via sort query parameter.

Filtering

GET /events end-point now requires filter[state] URL parameter. Full list of states supported by the filter are here.

Combining states in a filter is also supported.

Pagination

GET /events endpoint returns records via cursor-based pagination mechanism.

Image validation

Control API now validates image pixel size, file size and aspect ratio as per app spec.

422 on exceeding limits

When the maximum number of elements or events is reached and more can not be created via Control API (manually creation is not limited) the API now returns HTTP 422, rather than HTTP 429. This change was made because strictly speaking this limit is not a limit on a number of calls and therefore in most case it does not make sense to repeat the call, unlike when handling HTTP 429.

Account management

V2 adds account management end-points supporting account create, read and delete operations. These end-points are available only to tokens with super admin access.

App creation

Creating an app in the context of LViS Studio means loading an app spec into the Studio.

V2 adds an end-point for app creation. This end-point is available only to tokens with super admin access.

App spec

App spec loader

App spec loader validation has been improved with a goal of providing better diagnostic information if app spec loading fails:

• More data validation is done than in v22

• Stricter validation

• Clearer diagnostic messages are produced for validation errors

• Diagnostic messages include a reference to the exact file which has a problem

• Invalid SSL certificate errors are properly reported

• Corrupt JSON and incorrect MIME detection

User validation

​New rules are implemented for how requires_validated_user setting changes are handled on app spec reload and element cloning. The aim is to make it predictable and consistent.

Element duration

Element duration mode is configurable via app spec. The optional has_duration attribute is replaced with a mandatory duration attribute. This is done in order to create complete clarity and control for the app developer over what duration management mechanism will be used by the Studio. has_duration was very limited in what it could do, being a simple ON/OFF switch. duration allows three modes: instant, fixed and flexible, and allows the setting of a default duration via app spec. You can find full documentation here.

Safety

• Element is not migrated to new app spec during app spec update if derived_from is changed to prevent unexpected results.

Image validation

• Image width and height attributes are now mandatory (where optional in v22)

• New mandatory attribute file_size added to set maximum allowed file size for an image field.

Studio

Content management

• Added ability to stop an element early

• Width, height, aspect ratio and file size for uploaded images is validated by Studio and Control API image uploader. The validation rules are set up by the app developer within app spec. This feature helps to prevent images that are too big being published.

• Repeat events scheduler now takes "on demand" time into account, so that a repeat event is scheduled with requested delay only after the original event's "on demand" state is finished.

Certification control

In v23 if certification is enabled at element level, but disabled at project level, then the element is published with certification switched off. Full documentation is here.

UI

• Consistent language "Reveal answer" for revealing the correct answer is used on forms and in cog menu

• File size is displayed for each image within assets library

• Improved UI of 404 and 500 error pages

• Events that do not have audio delay setup are transitioned from "current" to "past" state on the timeline page bypassing the "on demand" state. For events which have audio delay setup the "on-demand" state lasts for the duration of the audio delay.

• UUIDs are displayed for elements (instead of numerical IDs), accounts, apps

Concurrency data tracking

A new mechanism is in place that can record spikes and sessions as short as 5 seconds.

Listings

In v22 if there was more than one qualifying past or future event starting at exactly the same time, then all such events were included in listings. This meant that the number of events in listings could be higher than limits set for the project.

In v23 the limits are enforced, so in this case not all of the events starting at the same time would be included in listings. You can find more information in the listings guide.

Performance

Content publishing latency has been reduced for some cases.

Tech Admin role

A new role has been added, which sits above "Admin" role. A Tech Admin is allowed to:

• Reload services and switch services on the project

• Access more sensitive service settings, e.g. keys (this assumes that the service was developed with this role in mind)

A Tech Admin can NOT add a service to LViS or reload a service at the LViS instance level. These require Super Admin level of access.

Please consult the roles matrix for more information.

Administration

• Account name is displayed in projects list on the service page

• Notification types required by the service are displayed on the service page

• Ability to select & copy data (accounts, projects, members names) on admin pages

Services

• static_host has been added to service instance handshake data to enable the service to use public feeds

• Project handshake and project update requests are merged into one

• "project" is changed to "projects" in the URLs to conform to REST resource naming

• IDs are replaced with UUIDs in

  • All LViS Services API endpoints including handshakes

  • Service notifications

  • Element prefill

  • Tabs URLs

Feeds

• id field now contains element UUID instead of integer ID and uuid field has been removed

Removals

• Control API v1

• Private data feeds. Please use Control API v2 instead.

• Combipoll element

• Proxy connections concurrency graph

JavaScript Lib

• A new form of setDelay method has been added. It calculates the delay based on the current video/audio/content stream timecode so that the app developer should not have to calculate the delay separately.

• ​getId method returns the element's UUID instead of the numerical ID

• signIn method is deprecated and replaced with login method. The principle difference between the two methods is that the latter one reports on success or failure of login operation, while the former does not.

Leaderboard

• In order to achieve consistency around naming various properties the user_id attribute has been renamed private_id. Full list of attributes is here.

• In order to be less cryptic the value attribute has been renamed score. Full list of attributes is here.

• URLs schema for event level leaderboards in Leaderboard WS has been changed to have a consistent approach across project and event level leaderboards. The event_id query parameter has been removed and event UUID incorporated into the URL instead, like this: /api/projects/{project_id}/events/{event_id}/leaderboards/{leaderboard_id}. New format is described here.