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 session duration, and if needed, we can build additional visualizations based on your bespoke 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 simply a collection of events that occurred within a specific window of time.

The most minimal approach to utilizing the metrics modules 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 this 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 (a platform default), the backend will time out. You can take steps to configure the default timeout if needed.

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 explicitly start an interaction 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 explicitlyStartInteracton(){
  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 endInteractionBeforeTimeout(){
  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 serve to 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/gumband-manifest.json
{
    "manifest": {
        "statuses": [...],
        "controls": [...],
        "settings": [...],
        "metrics": [
            {
                "interactionTimeoutMs": 15000 // a 15 second timout
            }
        ]
    }
}