Quick Start

This quick start guide explains how to integrate Gumband into your exhibit with the Gumband SDK, a NodeJS package, while keeping in mind the three key pillars of Gumband: Health, Content, and Metrics. In particular, you will learn:

The Gumband SDK contains a library of functions and a websocket connection manager to facilitate communication between your exhibit and the Gumband cloud. Optionally, it also includes a MQTT message broker to manage communication between your exhibit and Gumband Hardware.

Table of Contents

Installing and Initializing the Gumband SDK

Install the Gumband SDK as a new dependency in your node package: npm i @deeplocal/gumband-node-sdk.

Create a new exhibit in the Gumband UI and copy the exhibit ID and Authentication Token into a new .env file. You will use these two values to authenticate your exhibit with the Gumband Cloud.

.env

EXHIBIT_TOKEN=${alpha-numeric-string}
EXHIBIT_ID=${exhibit-id}

Initialize the Gumband SDK with the basic required parameters:

this.gumbandSDK = new Gumband(
    process.env.EXHIBIT_TOKEN,
    process.env.EXHIBIT_ID,
    `./manifest.json`,
);

where ./manifest.json is the path to a JSON file that defines the manifest. The manifest defines what statuses, controls, and settings will be available to your exhibit; more on statuses, controls, and settings below. A basic manifest.json would look like this:

{
    "manifest": {
        "statuses": [],
        "controls": [],
        "settings"
    }
}

When you run your node application, the Gumband SDK will authenticate itself with the Gumband Cloud and you’ll be able to see it come online:

Health

Monitoring Health with Statuses

Statuses are string values that can be set to track any state of your exhibit, so exhibit health can be monitored 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 GumbandSDK.setStatus(statusID: string, newStatus: string) function. For example, imagine you have a screen that can be in many states, and you’d like the state of the screen to be visible as a status in the Gumband UI:

function showDigitalSignageScreen() {
    //insert logic to switch screen to Digital Signage
    this.gumbandSDK.setStatus('screen-status', 'Digital Signage');
}

function goIntoStandbyScreenMode() {
    //insert logic to put screen in Stand By mode
    this.gumbandSDK.setStatus('screen-status', 'Stand By');
}

Note that screen-status matches the ID of the status defined in the manifest.

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

Dispatch Email Custom Notifications

When a critical component of your exhibit goes down, you want to know right away. Gumband has email notifications built-in for a number of use cases, such as Operation Mode change and the exhibit going offline/online, but you can also define your own custom email notifications with the GumbandSDK.notifications.email(customMessage: string) function:

thirdPartyIntegration.on('error', () => {
    this.gumbandSDK.notifications.email("An error occurred with the third party integration");
});

Each Gumband user can individually subscribe to the built-in notifications and any custom notifications you dispatch in the Exhibit Notifications tab:

Content

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 operation mode through the Sockets.OP_MODE_RECEIVED event listener callback on the SDK:

this.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.

Triggering Events with Controls

Controls are 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 are one-way communications from the Gumband cloud to the exhibit. You can listen for a control trigger through the Sockets.CONTROL_RECEIVED 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:

{
    "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 GumbandSDK.setSetting(settingID, newSettingValue: string | number | boolean) function in the SDK (Exhibit → Cloud), and a setting change event from the Gumband cloud can be listened for through the Sockets.SETTING_RECEIVED event listener callback (Cloud → Exhibit):

exhibitActionThatTriggersSettingChange(manifestId) {
    //where the manifestId is the "id" of the setting as set in the manifest.
    //In the example manifest above, the IDs are "header", "subheader", "body", and "main-image"
    this.gumbandSDK.setSetting(manifestId);
}

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.

Metrics

Measure User Interactions

Recording events to measure user interaction is easy with the Gumband SDK. Simply use the GumbandSDK.event.create(eventName: string, data: any) function to dispatch new events to the Gumband Cloud. For example, the following will dispatch 16 fake button press events:

createFakeButtonPressEvents() {   
    for (let i=0; i<10; i++) {
      await gb.event.create("Blue Button Press", {});
    }
    
    for (let i=0; i<5; i++) {
      await gb.event.create("Red Button Press", {});
    }
    
    await gb.event.create("Yellow Button Press", {});
};

which would result in the following events in the Gumband UI: