Skip to main content

Quick Start

This quick start guide explains how to integrate Gumband into your exhibit with our SDKs, each of which contains a library of functions and a websocket connection manager to facilitate communication between your exhibit and the Gumband platform.

Installing and Initializing the Gumband SDK​

Install the Gumband library:

terminal
npm i @deeplocal/gumband-node-sdk

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

.env
EXHIBIT_TOKEN=ae132...di2lk9
EXHIBIT_ID=1

Initialize the Gumband SDK with the basic required parameters:

Node Application
import { Gumband } from "@deeplocal/gumband-node-sdk";
import { MANIFEST } from "./manifest.js";

const EXHIBIT_TOKEN = "ae132...di2lk9";
const EXHIBIT_ID = 1;

this.gumbandSDK = new Gumband(
    EXHIBIT_TOKEN,
    EXHIBIT_ID,
    MANIFEST
);

where MANIFEST is a JSON object that defines what statuses, controls, and settings will be available to your exhibit; more on statuses, controls, and settings below. A basic manifest would look like this:

manifest.js
export const MANIFEST = {
  manifest: {
      statuses: [],
      controls: [],
      settings: []
  }
}

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

Component showing as connected with a green online indicator. An exhibit instance in the Gumband UI showing as online, as indicated by the green icon.

Health Monitoring​

Exhibit Statuses​

Statuses are string values that can track any state of your exhibit, allowing remote monitoring of exhibit health. 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.js
export const MANIFEST = {
  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: [],
  },
};

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

Status page showing two statuses. Two statuses shown on the Status page of 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 a simple function call. 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:

Node Application
...

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

The screen-status string matches the ID of the status defined in the manifest.

Log Messages​

note

This feature is currently only available through the Node SDK.

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:

Node Application
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:

Logging page showing logs sent from the application. The logs tab for an exhibit 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

Dispatching Email Alerts​

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 exhibit goes offline/online, but you can also define your own custom email notifications with one of the included library functions:

Node Application
...

//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'
    );
});

To subscribe to these notifications, please reach out to support@gumband.com. The ability to subscribe to them in the Gumband UI is coming soon!

Configuration and Content​

Configuring Settings​

Settings are configurations for your exhibit which could control anything from text copy to the RPMs of a motor, and, like statuses, they are also defined through the manifest:

manifest.js
export const 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,
            },
        ],
    },
};

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

Settings page showing four settings. Settings in the Gumband UI.

Settings can be set both in the Gumband UI and by the exhibit itself. If a setting is changed in the Gumband UI, a websocket event will be emitted through the Gumband SDK, which can be listened for through the SETTING_RECEIVED event:

Node Application
...

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

On the other hand, if the exhibit triggers the setting change, that new value will immediately be shown in the Gumband UI. The exhibit can change a setting through the a provided library function:

Node Application
...

function changeSetting(manifestId: String, newSettingValue) {
  //where the manifest_id is the "id" of the setting in the manifest.
  //In the example manifest above, the manifestIds are "header", "subheader", "body", and "main-image"
  this.gumbandSDK.setSetting(manifest_id, new_setting_value)
}

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

Creating Settings At Runtime​

Sometimes, an exhibit will need a way to introduce more settings at runtime. This typically occurs when you need to integrate with a variable number of similar external devices, and therefore it needs to be able to manage a variable number of groups of settings. For this use case, you can utilize the SettingsList setting type. Check out the guide on SettingsLists for more information.

Trigger Events with Controls​

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

manifest.js
export const MANIFEST = {
  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: [],
  },
};

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

Controls page showing two controls. Two control buttons in the Gumband UI.

Controls are one-way communications from the Gumband cloud to the exhibit. You can listen for a control event through the CONTROL_RECEIVED event listener callback through the SDK:

Node Application
...

this.gumbandSDK.on(Sockets.CONTROL_RECEIVED, async (payload) => {
    if (payload.id === 'toggle-game-mode') {
        this.toggleGameMode();
    } else if (payload.id === 'reload-frontend') {
        this.reloadFrontend();
    }
});

Manage Files Remotely​

With Gumband you can configure your exhibit to automatically download files that are uploaded to the Gumband UI:

Node Application
import { Gumband } from "@deeplocal/gumband-node-sdk";
import { MANIFEST } from "./manifest.js";

this.gumbandSDK = new Gumband(
  process.env.EXHIBIT_TOKEN,
  process.env.EXHIBIT_ID,
  MANIFEST,
  {
    //Gumband will download any files uploaded to Gumband and place them in the specified directory
    contentLocation: "./a/specified/directory"
  }
);

This constructor option tells the SDK that any files uploaded to Gumband for this exhibit should be downloaded to the specified directory. For more info on how to upload files to the Gumband UI, see the User Interface docs.

With the code, above, the SDK will automatically sync files from Gumband, but only when the Gumband class is first initialized. In order to sync files uploaded while the exhibit is running, you'll need to listen for the FILE_UPLOADED event and manually trigger a file sync:

Node Application
...

this.gumbandSDK.on(Sockets.FILE_UPLOADED, async (payload) => {
  console.log(`File uploaded: ${payload}`);

  //Sync local files with remote files.
  await gb.content.sync();
  console.log('Done updating files.');
});

Now your files will sync as soon as a new file is uploaded to Gumband.

Analytics​

note

As the analytics feature is the most complex module provided through the SDK, it is highly recommended that you read through our in-depth analytics guide before integrating it into your exhibit.

Gumband analytics is a feature set that allows you to draw meaningful insight as to how users are engaging with your exhibit. Out of the box, we provide a way to measure the number and duration of user interactions, but, if needed, additional visualizations can be added based on your specific use case. Check out our Charts Catalog for more information on what chart visualizations are available.

The most minimal approach to using the analytics module can be seen below:

Node Application
...

function handleBlueButtonPress() {
    this.gumbandSDK.metrics.create('Button Press', { buttonColor: 'Blue' });
}

This will send a "Button Press" event to Gumband with the included metadata object.