App Specs

An M/IC App Spec describes an M/IC App to the platform and dictates how Studio UI is setup, amongst other things. It is made of

  • Root spec - Contains top level settings and references to other JSON documents comprising the App Spec.

  • Elements - List of Elements this App supports along with settings for each element.

  • Fields - All of Project, Event and Element level settings refer to fields described in this document.

Root Spec

Root spec defines these properties:

Property

Description

Mandatory

Default

name

App name

yes

id

Unique app id. All versions of the same app have the same id.

yes

version

App version. Only one app with the same id and version can be available within LViS.

yes

base_apps_url

Base URL for App location.

yes

listings

Number of past and future events to include in listings. If not set then the values can be set via Studio UI.

no

project_settings

Project level settings spec URL.

no

no settings

event_settings

Event level settings spec URL.

no

no settings

elements

Elements spec URL.

no

no Elements

fields

Fields spec URL.

no

no fields

embed_url

App embed URL.

no

dash_image

App image URL. Image has to be 100 x 100 px. Make sure it works via HTTPS. This is the image displayed on the dashboard.

no

default app image

services

List of services required by application. Each service may have additional configuration.

no

empty list

curation

App requires social curation to be activated

no

false

schedule

App requires Event scheduling functionality

no

true

analytics

App requires Analytics functionality

no

true

live_activity

App requires Live Activity section on Timeline and Analytics pages

no

true

localisation

App supports localisation

no

false

{
"name": "The Big Question",
"id": "thebigquestion",
"version": "1.2.3",
"base_apps_url": "http://12341234.cloudfont.net/apps",
"listings": { "past": 1, "future": 2 },
"embed_url": "/app.html",
"dash_image": "/config/lvis/app-dash.png",
"fields": "/config/lvis/fields.json",
"elements": "/config/lvis/elements.json",
"project_settings": "/config/lvis/project_settings.json",
"event_settings": "/config/lvis/event_settings.json",
"services": {
"leaderboard": {
"max_score": 500000
},
"submissions": {}
},
"curation": true,
"schedule": true,
"analytics": false,
"live_activity": false,
"localisation": false
}

Conventions

These are merely conventions meant to standardise the structure of the apps. They are not enforced and neither used by M/IC Studio in any shape or form.

Root spec

/config/lvis/spec.json

Embed URL

/app.html

Dashboard app image

config/lvis/app-dash.png

Fields

config/lvis/fields.json

Elements

config/lvis/elements.json

Project settings

config/lvis/project_settings.json

Event settings

config/lvis/event_settings.json

Base App URL

Base App URL format

${base-apps-url}/${id}/${version}

Base App URL for above example

http://12341234.cloudfont.net/apps/thebigquestion/1.2.3

URLs

URLs specified in app spec can be absolute or relative. Relative URLs are relative to base app URL.

Dashboard image URL for example above

http://12341234.cloudfont.net/apps/thebigquestion/1.2.3/config/lvis/app-dash.png

Absolute URL may omit schema

//12341234.cloudfont.net/apps/thebigquestion/1.2.3/config/lvis/app-dash.png

Embed URL

Embedding and Previewing are enabled by adding embed_url to App Spec. They are disabled if embed_url in App Spec is not specified or set to null.

Services

Service configuration object is passed to LViS Service.

Leaderboard specific options

max_score

max score allowed for default leaderboard, where event id is used as leaderboard id

Reload

There are several scenarios which lead to project's App Spec update, such as

  • App Spec reload

  • Switching project App to different version

  • Switching project to different App

Migration rules

When App Spec is updated the content of the following entities is migrated to the latest App Spec:

  • Project settings.

  • Not finished events. Finished events are ignored.

  • Not published elements. Published elements are ignored.

The migration process described below:

Change

Action

Field is added to Element/Project settings/Event settings spec.

The field is added to the corresponding entity with empty (or default if present) value.

Field is removed from Element/Project settings/Event settings spec.

The fields is removed from corresponding entity.

Field's key in a specs is changed.

Same as sequential removing of the old field and adding the new one.

Field properties in the specs are changed.

Field properties are updated, existing value is converted to the new type (if type changed). Type conversion described in the next section.

Field definition removed.

All references to the field are automatically disabled and field disappears from UI, feeds, etc. If later this field definition is re-introduced then old references are automatically restored.

Field type conversion

These take place when new version of App Spec has the same field, but with a different type.

new field type

data conversion

string

string representation of old value is taken

boolean

"true" or "yes" string value converted to true, other values to false

number

value representing a number is converted to number, otherwise value is converted to null