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:

Open

Health

• How to monitor exhibit health with Statuses

• How to log info, debug, warning, and error messages to Gumband

• How to create and trigger custom email notifications

Open

Content

• How to control the operation mode of your exhibit

• How to create and trigger custom exhibit events with Controls

• How to create custom configurations with Settings

Metrics

• How to measure user interactions with reporting events

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 can also initialize an 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

Initialize the Gumband SDK with the basic required parameters:

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:

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

Health

Monitoring Health with Statuses

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

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 a status in the Gumband UI:

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:

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 Custom Email 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 when the Operation Mode changes or the exhibit goes offline/online, but you can also define your own custom email notifications with the GumbandSDK.notifications.email(customMessage: string) function:

Each Gumband user can individually subscribe to the built-in notifications or 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 can be toggled 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:

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:

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:

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:

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), or they can be set through the Gumband UI, which can be listened for through the Sockets.SETTING_RECEIVED event listener callback (Cloud → Exhibit):

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:

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