What is Gumband Metrics?

Gumband metrics is a feature set that allows you to draw meaningful insight as to how users are utilizing your exhibit. Out of the box, we provide a way to measure the number of user interactions and the session duration, and, if needed, we can build additional visualizations based on your specific use case.

When measuring the engagement of your exhibit we have two basic concepts to understand: “events” and “interactions”.

Events are singular moments in time when something happens on the exhibit, typically due to a user action like a button push. An Interaction is a collection of events that occurred within a specific window of time, typically representing a single, complete user experience of the exhibit.

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

// File: your-code.js
const { Gumband } = require('@deeplocal/gumband-nodejs-sdk')
// or import { Gumband } from '@deeplocal/gumband-nodejs-sdk'

const gb = new Gumband(EXHIBIT_TOKEN, EXHIBIT_ID, PATH_TO_MANIFEST)

function handleButtonPress(){
  gb.metrics.create("Button Press", {buttonColor: "Blue"})
}

You get to choose the value of the event name (“Button Press”) and the payload ({buttonColor: "Blue"}). Once you call the metrics.create function, the backend of Gumband will take this and any subsequent events and bucket them into the same interaction. If there is a lapse in events for 60 seconds (the platform default), the backend will time out the interaction. You can take steps to configure the interaction timeout if needed.

Remember that an event that describes how and when a user is interacting with your exhibit is much more interesting than one that simply describes how your exhibit works. For instance, you would not want to fire an event just because the content changed on a passive screen UNLESS that particular change was triggered by the user.

How to Start an Interaction without User Input

In the above example we used the minimalist approach of starting an interaction only when a user conducts some action. If you need to start an interaction without a user action you can do so with gb.metrics.startInteraction()

// File: you-code.js
const { Gumband } = require('@deeplocal/gumband-nodejs-sdk');
// or import { Gumband } from '@deeplocal/gumband-nodejs-sdk';

const gb = new Gumband(EXHIBIT_TOKEN, EXHIBIT_ID, PATH_TO_MANIFEST)

function startInteractonWithoutUserAction(){
  gb.metrics.startInteraction(); // 👈 an arbitrary payload, defaults to {}
}

function handleButtonPress(){
  gb.metrics.create("Button Press", {buttonColor: "Blue"});
}

How to End an Interaction Before Timeout is Reached

There may be instances where you need to end the interaction before the default timeout elapses. For this use case we provide the metrics.endInteraction() method.

// File: Game.js
const { Gumband } = require('@deeplocal/gumband-nodejs-sdk');
// or import { Gumband } from '@deeplocal/gumband-nodejs-sdk'

const gb = new Gumband(EXHIBIT_TOKEN, EXHIBIT_ID, PATH_TO_MANIFEST);

function handleButtonPress(){
  gb.metrics.create("Button Press", {buttonColor: "Blue"});
}

function docentManuallyResetsExhibit(){
  gb.metrics.endInteraction(user);
}

Calling gb.metrics.endInteraction() will take any interaction that is “open” and will close it, no longer accepting new events. Any subsequent events (either with create() or startInteraction()) will open a brand new interaction.

How to Configure the Interaction Timeout

Previously, we had discussed how the Gumband backend waits 60 seconds without seeing any new events before it closes the interaction. Any new events will reset the 60 second countdown. Consequently, as long as your events continue to arrive in a timely manner, you can certainly have an interaction that lasts much longer than 60 seconds. In theory you can create an infinite event if you keep sending in gb.metrics.create events!

We do provide the ability to change the default interaction timeout for your exhibit within certain bounds.

The minimum value is 5000 (5 seconds).

The maximum value is 900000 (15 minutes).

If you wish to override the default of 60 seconds, you can update your manifest.json to look like this

// my-gumband-project/manifest.js
export const MANIFEST = {
    manifest: {
        statuses: [...],
        controls: [...],
        settings: [...],
        metrics: [
            {
                interactionTimeoutMs: 15000 // a 15 second timeout
            }
        ]
    }
}

How To Handle Multiple Concurrent Interactions

Some exhibits may have multiple users interacting with it at one time. To handle this scenario, Gumband provides additional methods which specific interaction an event belongs to. These functions mirror the regular create, startInteraction, and endInteraction, and are called createConcurrent, startConcurrentInteraction, and endConcurrentInteraction. The only difference is that these methods take an interactionId and always return the interactionId with which their event will be associated. To start an interaction, simply call either the createConcurrent or startConcurrentInteraction methods without an interactionId and we will generate one for you:

// File: your-code.js
const { Gumband } = require('@deeplocal/gumband-nodejs-sdk')
// or import { Gumband } from '@deeplocal/gumband-nodejs-sdk'

const gb = new Gumband(EXHIBIT_TOKEN, EXHIBIT_ID, PATH_TO_MANIFEST);

function exhibitWokenFromIdleState() {
  let interactionId = gb.metrics.createConcurrent('Exhibit Woken', {});
  
  console.log(interactionId);
  // 0357892a-68e0-49cc-bf2d-18a8ca563f68
}

To add more more events to the same interaction, add the returned interactionId on subsequent event calls:

function contentSelected(interactionId) {
  gb.metrics.createConcurrent('Content Selection', { name: "content" }, interactionId);
}