Page Comparison

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:

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:

Image Removed

You can listen for changes in the operating 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.

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:

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

EXHIBIT_TOKEN=ae132...di2lk9
EXHIBIT_ID=1

Initialize the Gumband SDK with the basic required parameters:

const { Gumband } = require("@deeplocal/gumband-node-sdk");

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": [
            {
      ],
         "idcontrols": "screen-status",
    [],
           "typesettings": "String",[]
                "display": "Screen is currently showing:",
                "order": 0
            },
            }
}

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

Image Added

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:

{
       "manifest": {
        "idstatuses": "last-game-played",[
            {
         "type       "id": "Stringscreen-status",
                "displaytype": "Last game played:String",
                "orderdisplay": 1"Screen is currently showing:",
         }       "order": 0
  ],         "controls": [] },
        "settings": []    {
                "id": "last-game-played",
              }
}

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

Image Removed

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 in the SDK. For example, imagine that a screen should toggle on and off according to the operation mode:

this.gumbandSDK.on(Sockets.OP_MODE_RECEIVED, (payload) => {
    if(payload.value) {
      this.gumbandSDK.setStatus('screen-status', 'Digital Signage');
      "type": "String",
                "display": "Last game played:",
                "order": 1
            }
        ],
        this.turnScreenOn();
    } else {
      this.gumbandSDK.setStatus('screen-status', 'Off');"controls": [],
        "settings": []
    this.turnScreenOff();
    }
});

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

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:

Image Removed

}
}

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

Image Added

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:

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:

Image Added

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:

//listening for errors on a connection to some generic third party integration
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 or any custom notifications you dispatch in the Exhibit Notifications tab:

Image Added

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:

Image Added

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.CONTROLOP_MODE_RECEIVED, async (payload) => {
    console.log(`Control`received op triggeredmode: ${payload.idJSON.stringify(payload)}`);
  
      if(payload.id === "toggle-game-mode"value) {
      console.log('OP  this.toggleGameMode(mode now on'); 
    } else if (payload.id === "reload-frontend") {
       
        this.reloadFrontend(console.log('OP mode now off');
    }
});

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:

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": [],
        "settings": [    {
        {                 "id""id": "headerreload-frontend",
 
              "type": "TextInputSingle",

               "display": "HeaderReload CopyFrontend",
                "default": "Gumband Demo",
                "order": 0
            },
            {
                "id": "subheadertoggle-game-mode",

               "type": "TextInputSingle",

               "display": "SubheaderToggle Copy",
                "default": "Digital Signage"Game Mode",
                "order": 1
            },
        ],
   {     "settings": []
          "id": "body",
                "type": "TextInput",
          }
}

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

Image Added

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}`);
    
 "display": "Body Copy if(separate by | for new paragraph)",payload.id === "toggle-game-mode") {
        this.toggleGameMode();
    } else if (payload.id === "defaultreload-frontend":) "Gumband is an interactive experience tool",{        
        this.reloadFrontend();
 "order": 2             },
  }
});

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": [],
        "idcontrols": "main-image",[],
        "settings": [
          "type": "FileSelection",  {
                "displayid": "Image Assetheader",
                "ordertype": 3"TextInput",
             }   "display": "Header Copy",
   ]     }
}

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

Image Removed

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, and a setting change event from the Gumband cloud can be listened for through the Sockets.SETTING_RECEIVED 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:

Image Removed

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

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() {        "default": "Gumband Demo",
                "order": 0
            },
            {
                "id": "subheader",
                "type": "TextInput",
                "display": "Subheader Copy",
                "default": "Digital Signage",
                "order": 1
            },
            {
for  (let i=0; i<10; i++) {       await gb.event.create("Blue Button Press", {});
"id": "body",
   }          for (let i=0; i<5; i++) {
      await gb.event.create("Red Button Press", {}); "type": "TextInput",
     }          await gb.event.create("Yellow Button Press", {});
};

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

Image Removed

Dispatch Email Custom Notifications

When a critical component of your exhibit goes down, you want 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):

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:

Image Removed

 "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:

Image Added

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):

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

Image Added