Define your App

How to use App Specs to define your app to the platform before writing the business logic

Your app is described to the platform by App Spec files which you control and update via Studio's Developer interface.

App Specs tell Studio how to display your App Setup settings, interactive content Elements, and other Services. Learn more about App Spec files here.

Let's make your first App Spec.

Create your App Spec

The App Spec has a root and then child JSON files which describe amongst other things:

• Elements: which content Elements are enabled such as poll, vote or prediction

• Configuration in Studio: how your users will configure styling, object visibility, gamification settings

• Extensions: which features are enabled, for example, Gamify, Identify, Vote, or Forms

Example Root App Spec file:

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

When developing a new app from scratch, you’ll first need to upload a starter App Spec which you can edit later.

You can download the app spec below as a basis, but please ensure you follow the next section to update the relevant parts.

2KB

starter_app_spec.zip

archive

Create an empty App Spec

The first step in the creation of an App Spec is to create the required JSON files. The resulting file structure should look like this:

Where:

• elements.json and fields.json contain an empty array

• project_settings.json contains a JSON object with a property called sections that contains an empty array.

• spec.json contains an empty JSON object.

Once the structure is created, update the spec.json file with the following content:

{
  "name": "Hello world",
  "id": "hello-world",
  "version": "0.0.1",
  "schedule": true,
  "base_apps_url": "https://yourhosting.com/apps",
  "dash_image": "https://yourhosting.com/images/my-app-dashboard-image.png",
  "fields": "fields.json",
  "elements": "elements.json",
  "embed_url": "https://yourhosting.com/apps/index.html",
  "project_settings": "project_settings.json",
  "localisation": true
}

Where:

• name is the user-friendly name that will be visible in Studio

• id is the unique identifier for the app

• version is the version of the app. We recommend using semantic versioning.

• schedule specifies whether events are supported in the project or not.

• base_apps_url is the Base URL for App location.

• dash_image is the URL to the app logo that will be displayed in Studio

• fields is a pointer to the fields.json file that you have created alongside spec.json. This guide assumes you’ll upload these files to a server so you have https://yourhosting.com/apps/spec/spec.json alongside https://yourhosting.com/apps/spec/fields.json and so on

• elements is akin to fields, but pointing to elements.json

• embed_url is the URL that will be used when embedding your app

• project_settings is akin to fields but pointing to project_settings.json

• localisation specifies whether to support multiple locales or not in the app.

Add Project Settings into the App Spec

Open the project_settings.json file in your text editor and add the following lines:

{
  "sections": [
    {
      "name": "My section",
      "subsections": [
        {
          "name": "My subsection",
          "description": "You can use project settings to host project wide metadata and configuration",
          "properties": [
            {
              "label": "Title",
              "key": "app_title",
              "field": "text",
              "default": "My app's title",
              "description": "The title of the app."
            }
          ]
        }
      ]
    }
  ]
}

With this settings file you’ll be able to specify the title of your application from Studio. This may seem a bit trivial, but the same mechanism can power plenty of functionality within your app such as:

• White labelling and styling your UI

• Feature flagging

• Hosting metadata of your app

• Reacting in real-time to changes in the metadata

Add a Poll Element into the App Spec

As it stands, your App Spec will not yet have defined any interactive Elements. Let’s go ahead and create a Poll Element so we can add interactivity in our app.

To do so, open elements.json in your text editor and enter the following JSON:

[
  {
    "name": "Poll",
    "content_type": "poll-element",
    "derived_from": "poll",
    "duration": {
      "mode": "fixed",
      "default": 60
    },
    "icon": "fal fa-question-circle",
    "colour": "#1F5DFF",
    "label": "{{question.text}}",
    "label_question": "{{question.text}}",
    "label_option": "{{option.text}}",
    "reveal_results": {
      "modes": ["vote", "always", "close", "manual", "never"],
      "default": "always"
    },
    "certification": {
      "default": true
    },
    "question": [
      {
        "label": "Title",
        "key": "text",
        "field": "text",
        "mandatory": "question

Deploy your App Spec to a public URL

In order to use your App Spec, the platform needs to be able to load its files from the internet, so make sure you can see them if you paste the URL into your browser. There are at least two ways to achieve this:

1. Upload the production build to the CDN of your choice. This approach is useful when you want to distribute the final result to all users.

2. Expose the local server to the public using a tunneling service, such as ngrok or localtunnel. This method is useful when you want to tinker with the source code and check the changes in real time.

During development, you’ll likely want to iterate through changes in App Spec quickly. We find that exposing your local copy of the App Spec by a reverse proxy services maximises developer efficiency by reducing deployment delays.

To upload the production build to a Content Delivery Network (CDN), various options are available. At Monterosa, we utilise AWS S3 along with the AWS CLI for transferring files to the CDN:

aws configure set region <aws-region>
aws s3 sync ./dist/ s3://<bucket-name>/hello-world/ --cache-control max-age=60