What is Gumband

...

Analytics?

Gumband metrics analytics 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.

...

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.

...

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!

...

// 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
}

You will need to keep track of this interactionId while the interaction is ongoing. 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);
}