Services

A "Service' is a way to extend platform functionality without changing the core platform codebase.

A Service must implement

A Service can visually integrate into Studio, aid data collection from a Producer and provide data for the App and feeds by providing

A Service can subscribe to Notifications to be notified of data changes made within the platform.

All requests between Service and the platform are signed for security reasons. See Signing requests.

Signing requests

All requests to 3rd party service are backend-to-backend and signed with Service access token. Access token is created Service deployment time, stored in both service and the platform, and not communicated between them (pre-shared).

Signature calculation

signature = SHA1(access_token + signeable_content + salt)

signable_content is a concatenation of the following:

  • Resource path (including leading slash, e.g. ”/path/to/script”)

  • Query string (including leading question mark, e.g. ”?attr=value”)

  • POST data

salt is a random string, it should change from request to request and be sufficiently random.

Salt and generated signature are sent in HTTP headers:

  • X-LViS-Salt

  • X-LViS-Signature

Receiving end calculates signature from the access_token stored locally and data from the request and checks if it matches the one in the request. Any request failing signature check must return 403 forbidden.

Instance handshake

To add a Service to a platform instance, super admin provides three parameters:

  • Base URL

  • Access token

  • Name. Used to identify the service in LViS UI.

To complete adding a Service, the platform sends an Instance handshake request to it.

Raise a support ticket to organise new Service setup tasks

Service types

  • leaderboard

  • submissions

  • demographics

  • timerelease allows to set a lock on assets, like images uploaded for a media element, so that even if client application knew the url to the asset the user would not be able to view it until as specific point in time.

Project handshake

An application specifies which service(s) it needs. When a project is created, the platform enables all required Services automatically.

The platform sends a Project handshake request to the Service in such cases:

  • a new service has been added to the project

  • service config in the app is changed

  • project name is changed

Studio Tabs

Tabs are entries in Studio main menu.

Tabs are fetched by sending a request to the service when a project or an event is selected in Studio:

Auth endpoint

A Service can check users access rights making Project access or Super admin access request.

Project access

get
Project access

https://environment.lvis.io/p/:project_id/sessions/:user_session_token?service_id=demographics
Request
Response
Request
Path Parameters
project_id
required
string
ID of the project.
user_session_token
required
string
User session token.
Query Parameters
service_id
required
string
Service identifier.
Response
200: OK
{
"id": 3, // authenticated user id
"role": "producer" // user's role in context of requested project
}
401: Unauthorized
{}

Super admin access

get
Super admin access

https://environment.lvis.io/sa_sessions/:user_session_token?service_id=demographics
Request
Response
Request
Path Parameters
user_session_token
required
string
User session token.
Query Parameters
service_id
required
string
Service identifier.
Response
200: OK
{
"id": 3, // authenticated user id
"role": "super_admin" // user's role in context of requested project
}
401: Unauthorized
{}

Notifications

The purpose is to allow a Service to use Studio as Event/Element management system, where some processing is done by the Service. To enable this Studio notifies the service whenever data changes are made in Studio. When notified the Service then fetches up-to-date data from the platform using feeds or Control API.

Please note that notification does not guarantee that any of the data was actually changed after the previous notification, or that the current state of the object is final and complete. So service should track changes by itself.

There can be a lag of a couple of seconds between a change and notification.

On success service needs to respond with 200 and empty body.

On error service needs to respond with corresponding status and empty body.

These are supported notification types:

Analytics API

This API allows adding a tab with Service analytics data to the Event's analytics page. The platform enables this feature according to corresponding flag in instance handshake response. The platform makes Analytics request to the Service to get it's data.

Field data source

Service can act as a data source for a custom field, providing dynamic content.

Assets

Service can provide assets which LViS passes to the App. The platform fetches assets from the service by calling Assets.

Service feeds

Each service can provide service-specific data feeds. These feeds will be requested from the service and uploaded to the public CDN by the platform. Feeds list is configured during instance handshake in the handshake response.

Event feeds are uploaded periodically while event is running. The platform fetches Service specific Event data feed by calling Event-level feed.

Uploaded public feed will be listed on the Event feeds page, and available at the following URL:

//<static_host>/events/<first two chars of event uuid>/<event uuid>/<service_type>/<feed_id>.json