Quick Start

An exhibit can communicate with the Gumband cloud through the Gumband SDK, a NodeJS package. The SDK communicates with the Gumband cloud via a REST API, and receives events from the Gumband cloud through websockets. For more details on how to install the Gumband SDK into your node project, please see the Tutorial section.

Handling Operating Modes

An exhibit has two operating modes in Gumband: on or off. The operating mode toggle can be changed through the Gumband UI:

You can listen for changes in the operating mode through the event listener callback on the SDK:

gumbandSDK.on(Sockets.OP_MODE_RECEIVED, (payload) => {
    console.log(`received op mode: ${JSON.stringify(payload)}`);
    if(payload.value) {
      console.log('OP mode now on'); 
    } else {
      console.log('OP mode now off');
    }
});

The operating mode can be used in whatever way makes the most sense for your exhibit. For example, for signage it might toggle the screen on and off to conserve power; for an exhibit with many moving parts, perhaps it stops all motion.

Monitoring Health with Statuses

Statuses are string values that can be set to track any state of your exhibit, so you can monitor exhibit health remotely. The statuses available for your exhibit are unique per exhibit and must be configured through the manifest (learn more about the manifest in the Exhibit Manifest Configuration doc). For example:

{
    "manifest": {
        "statuses": [
            {
                "id": "screen-status",
                "type": "String",
                "display": "Screen is currently showing:",
                "order": 0
            },
            {
                "id": "last-game-played",
                "type": "String",
                "display": "Last game played:",
                "order": 1
            }
        ],
        "controls": [],
        "settings": []
   }
}

would configure statuses for the following exhibit instance in the Gumband UI:

There is no event listener for when a status changes, since statuses are one-way communications from the exhibit to the Gumband cloud. A status can be updated through the setStatus function in the SDK:

this.gumbandSDK.setStatus('screen-status', 'Digital Signage');

Triggering Events with Controls

Controls are one-time events that can be triggered through the Gumband UI. Common use cases for controls are rebooting an application that runs an exhibit or triggering some sort of test content or animation to help with debugging. Like statuses, controls are unique per exhibit and must be configured through the manifest. For example:

{
    "manifest": {
        "statuses": [],
        "controls": [
            {
              "id": "reload-frontend",
              "type": "Single",
              "display": "Reload Frontend",
              "order": 0
            },
            {
              "id": "toggle-game-mode",
              "type": "Single",
              "display": "Toggle Game Mode",
              "order": 1
            }
        ],
        "settings": []
    }
}

would configure controls for the following exhibit instance in the Gumband UI:

Controls can be thought of as the inverse of statuses: they are one-way communications from the Gumband cloud to the exhibit. You can listen for a control trigger through the event listener callback on the SDK:

this.gumbandSDK.on(Sockets.CONTROL_RECEIVED, async (payload) => {
    console.log(`Control triggered: ${payload.id}`);
    
    if(payload.id === "toggle-game-mode") {
        this.toggleGameMode();
    } else if (payload.id === "reload-frontend") {        
        this.reloadFrontend();
    }
});

Configuring Settings

Settings are configurations for your exhibit, and can be thought of as two way communications between the Gumband cloud and your exhibit. Settings will be the most unique between exhibits and could configure anything from text copy to the RPMs of a motor. Settings are also configured through the manifest. For example:

{
    "manifest": {
        "statuses": [],
        "controls": [],
        "settings": [
            {
                "id": "header",
                "type": "TextInput",
                "display": "Header Copy",
                "default": "Gumband Demo",
                "order": 0
            },
            {
                "id": "subheader",
                "type": "TextInput",
                "display": "Subheader Copy",
                "default": "Digital Signage",
                "order": 1
            },
            {
                "id": "body",
                "type": "TextInput",
                "display": "Body Copy (separate by | for new paragraph)",
                "default": "Gumband is an interactive experience tool",
                "order": 2
            },
            {
                "id": "main-image",
                "type": "FileSelection",
                "display": "Image Asset",
                "order": 3
            }
        ]
    }
}

would configure settings for the following exhibit instance in the Gumband UI:

Since settings are two way communications, they can be set by the exhibit through the setSetting function in the SDK, and a setting change event from the Gumband cloud can be listened for through the event listener callback:

exhibitActionThatTriggersSettingChange(settingId) {
    this.gumbandSDK.setSetting(settingId);
}

this.gumbandSDK.on(Sockets.SETTING_RECEIVED, (payload) => {
    console.log(`${payload.id} setting updated to: ${payload.value}`);

    this.updateFrontendFromSettings();
});

There are many different types of settings for various use cases. See the Exhibit Manifest Configuration doc for a complete list.

Logging Messages to Gumband

Gumband can be used to capture various types of logs. There are four different function calls in the SDK to dispatch different levels of logs to the Gumband cloud for your exhibit:

this.gumbandSDK.logger.debug('This is a debug log');
this.gumbandSDK.logger.info('This is an info log');
this.gumbandSDK.logger.warn('This is a warn log');
this.gumbandSDK.logger.error('This is an error log');

These calls would create the following logs in the Gumband UI:

1. Debug logs will remain in the Gumband cloud for 24 hours

2. Info logs will remain for 72 hours

3. Warn logs will remain for 1 week

4. Error logs will only be deleted when a user deletes them

Measure User Interactions

Dispatch Email Custom Notifications