Developing with Constellation

The apps in Constellation Apps are built using JavaScript. This approach ensures maximum flexibility, while also offloading many performance and security concerns to the rendering engine. It also makes developing your own app surprisingly easy!

Constellation Apps provides a JavaScript module, constellation_app_common.js, that enables easy connection with Constellation. In just a few lines of code, you can have an app up and running! Here is the complete code to create a blank Constellation app (the JavaScript file, at least):

import * as constCommon from 'constellation_app_common.js'

function loadDefinition (definition) {
  // A function to configure your app's content
  // based on the provided configuration.
  ... 
}

function parseUpdate (update) {
  // A function to respond to commands from
  // Control Server.
  ...
}

constCommon.configureApp({
  name: 'other',
  loadDefinition: loadDefinition,
  parseUpdate: parseUpdate
})

Note that constellation_app_common.js is a JavaScript module, so your file must also be a module.

Definitions

Definitions are user-provided configuraitons for your app. Users can use the Other App setup page in Constellation Apps to pass parameters to your app. Based on those parameters, you can configure the app as needed. These parameters are given in the parameters field of the defintion:

{
  ...
  parameters: {
    'parameter 1': 'value 1',
    'parameter 2': 'value 2'
  },
  ...
}

You can ignore the other fields in the definition, as they are for interal Constellation use.

Updates

If your user is using Control Server, your app will check in with the server every five seconds. This updates the Control Server web console and retrieves any updates from the server.

Interaction status

Your app can communicate whether it is in active use by setting the value of constCommon.config.currentInteraction. Set the value to true when interaction begins and false when it ends. One common way of defining "ends" is when the attractor is shown again. Properly setting this variable helps your user understand how the app is being used and enables them to collect analytics.

Responding to commands

Control Center may send a command in response to a user action, an event in the schedule, or another app. Built-in commands, such as refreshing, restarting, and shutting down, are handled automatically by Constellation.

Using the parseUpdate() function, your app can respond to custom commands.

Reading and writing local data

You can read and write local data by using constCommon.makeHelperRequest(). For example, here is the code used to save votes from Voting Kiosk:

constCommon.makeHelperRequest(
  {
    method: 'POST',
    endpoint: '/data/write',
    params: {
      name: 'votingData',
      data: {
        option1: 5,
        option2: 8
      }
    }
  })

makeHelperRequest() returns a Promise that resolves with two fields. The boolean success and the string reason. If the write fails, reason will provide helpful details.

/data/write POST

Write a JavaScript object to disk. Each request will write one line of JSON to the file. The user can download the file as a CSV spreadsheet from the Constellation Apps configuration page.

{
  data: {
    key1: 'value1',
    'key 2': ['value 2', 'value 3']
  },
  name: 'myDataFile'
}

data Object

A JSON-serializable object.

name String

A string filename without an extension. The extension '.txt' will be appended.

/data/writeRawText POST

Write the given text to file for later retrieval. If you wish to write JSON, you must call JSON.stringify() yourself first.

{
  text: 'A string of text',
  mode: 'a',
  name: 'myDataFile'
}

text String

The text to be written to file.

mode String

Pass 'a' (default) to append to the file or 'w' to overwrite the file.

name String

A string filename without an extension. The extension '.txt' will be appended.

/data/getRawText POST

Retrieve a previously-written data file.

{
  name: 'myDataFile'
}

name String

A string filename without an extension. The extension '.txt' will be appended.

When building an app using Python, Java, .NET, etc., you must communicate with Control Server manually.

Ping

Constellation uses a client-server model. To connect your app to Control Server, you should send a JSON object to the server every five seconds. Constellation calls this a ping. The ping object should have the following format and be sent as a POST request to the endpoint /system/ping:

{
  currentInteraction: true,
  group: 'My Group',
  helperAddress: '192.168.1.27:8000',
  id: 'My ID',
  permissions: {
    audio: true,
    refresh: true,
    restart: true,
    shutdown: false,
    sleep: false
  }
}

currentInteraction Boolean

Boolean value that should be true if the user is currently interacting with the app or false if they are not (or this is not an interactive app).

group String

String value with a user-provided value.

id String

String value with a user-provided value. Every Constellation app must have a unique id.

permissions Object

A dictionary defining how Control Server may command the app.

Ping response

When Control Server receives a ping, it will respond with a JSON object. That object will have the following structure:

{
  app: 'other',
  commands: [],
  current_exhibit: 'An Exhibit',
  definition: '',
  description: 'Some user-provided text describing this interactive.',
  error: '{}',
  permissions: {
    audio: true,
    refresh: true,
    restart: true,
    shutdown: false,
    sleep: false
  }
}

Most of these fields are for internal Constellation use. However, your app should respond to the follwoing fields:

commands Array

An array of string values representing commands from Control Server.

permissions Object

This dictionary represents the user's desired permissions. If reasonable, you should update your internal permissions to align with these.