Python Library

Welcome to the Gumband Python SDK. All methods described here are available on the Gumband class.

Configuration Options

Here is the list of the configuration options that the SDK constructor takes as parameters:

def __init__ (
    self, 
    exhibit_id: int, 
    token: str, 
    manifest: str | dict, 
    options: GumbandOptions = {}
)

arg	type	description
exhibit_id	int	The ID of the exhibit
token	str	The Authentication token for this exhibit
manifest	str \| dict	A path to a json file of the manifest, or a dictionary of the manifest object (default: `{}`)
options	GumbandOptions	Configuration options (default: `GumbandOptions()`)

Optional parameters provided through GumbandOptions:

arg	type	description
environment	str	The environment your exhibit is connected to, such as 'app' or 'custom' (default: 'app'). This should almost always be "app"
custom_server_ip	str	Custom server IP to connect to if you are not connecting to app.gumband.com.
content_location	str	The path to local content storage directory to where files uploaded to the Gumband UI will sync. Without this configuration option, the SDK will not sync down files (default: None).
skip_organization_file_sync	bool	Whether the SDK should skip file syncing of workspace-level files. Workspace files are those shared between exhibits via our integrated CMS. Most exhibits would not want to both downloading all of these files (default: True).
interaction_timeout	int	The timeout for user interactions in milliseconds. This is the length of time that must elapse between user events before the interaction will be automatically timed out by Gumband (default: 60000).

connect

connect() -> Promise<void>

Authenticates and establishes a WebSocket connection with Gumband and syncs content files if applicable. This must be called after initializing the Gumband class in order to connect the exhibit to Gumband.

Usage Example
from gumband_python_sdk import Gumband, GumbandOptions
from gumband_python_sdk.constants import SocketEventType

class GumbandService:
    def __init__(self, exhibit_id, token, manifest):
        """
        Initialize the GumbandService with necessary parameters.
        """
        self.gumband = Gumband(exhibit_id=exhibit_id, token=token, manifest=manifest,
                            options=GumbandOptions(content_location="./content"))
        
    async def start(self):
        """
        Start the Gumband connection and keep it running.
        """
        await self.gumband.connect()
        while True:
            await asyncio.sleep(1)

# Instantiate and run
if __name__ == "__main__":
    handler = GumbandService(
        exhibit_id=exhibit_id,
        token=exhibit_token,
        manifest=manifest,
    )
    asyncio.run(handler.start())

get_manifest

get_manifest() -> Promise<dict>

Retrieves the manifest from Gumband, including all status and setting values.

Usage Example
manifest = await gumband.get_manifest()
print(manifest)
# {
#     "id": 1,                         //The exhibit ID
#     "type": "custom-application",    //The type of exhibit component this is
#     "name": "Gumband SDK Tutorial",  //The name of the exhibit in the Gumband UI
#     "mqttPath": None,                
#     "online": True,                  //Whether the exhibit is online
#     "settingLists": [...],           //SettingsLists and their inner settings
#     "settingGroups": [...],          //SettingsGroups and their inner settings
#     "settings": [...],               //All settings outside a list or group and their values
#     "statuses": [...],               //All statuses in the manifest and their values
#     "controls": [...],               //All controls in the manifest
#     "strapiContent": []              
# }

set_status

set_status(status_manifest_id: str, status_value: str) -> Promise<Response>

Sets the status value for the provided manifest ID.

status_manifest_id: The ID of the status defined in the manifest.

status_value: The string value to which to set the status.

Usage Example
await gumband.set_status(status_manifest_id, status_value)

get_status

get_status(status_manifest_id: str) -> Promise<dict>

Retrieves the status for the provided manifest ID.

status_manifest_id: The ID of the status defined in the manifest.

Usage Example
status = await gumband.get_status(status_manifest_id)
print(status)
# {
#     "ExhibitId": 1,                           //The ID of the exhibit with which this status is associated
#     "manifestId": "my_manifest_id",           //The id of this status as defined in the manifest
#     "StatusGroupId": None,                    //The manifest ID of the group of statuses to which this status belongs
#     "type": "String",                         //The type of this status
#     "display": "Status Display Text",         //The display label for this status in the Gumband UI
#     "value": "current status value",          //The current value to which the status is set
#     "default": "",                            //The default value of the status
#     "order": 0,                               //The order in which this status appears in the Gumband UI
#     "createdAt": "2025-02-10T16:27:22.744Z",  //When this status was created
#     "updatedAt": "2025-02-11T16:54:36.543Z"   //When this status was last updated
# }

set_setting

set_setting(setting_manifest_id: str, setting_value: Any) -> Promise<dict>

Sets the setting value for the provided manifest ID.

setting_manifest_id: The ID of the setting defined in the manifest.

setting_value: The value to which to set the setting.

Usage Example
await gumband.set_setting(setting_manifest_id, setting_value)

get_setting

get_setting(setting_manifest_id: str) -> Promise<dict>

Retrieves the setting for the provided manifest ID.

setting_manifest_id: The ID of the setting defined in the manifest.

Usage Example
setting = await gumband.get_setting(setting_manifest_id)
print(setting)
# {
#   "ExhibitId": 464,                           //The ID of the exhibit with which this setting is associated
#   "manifestId": "ux_mode",                    //The id of this setting as defined in the manifest
#   "type": "SingleButtonGroup",                //The type of this setting
#   "display": "UX Mode",                       //The display label for this setting in the Gumband UI
#   "value": "my current value",                //The current value to which the setting is set
#   "default": "default value",                 //The default value of the setting
#   "order": 0,                                 //The order in which this setting appears in the Gumband UI
#   "createdAt": "2025-02-10T16:27:23.273Z",    //When the setting was created
#   "updatedAt": "2025-02-10T16:27:23.273Z"     //When the setting was last updated
# }

create_event

create_event(event_name: str, event_data: dict) -> Promise<void>

Sends a user interaction event to Gumband.

event_name: The name of the user event; e.g. "Button Press", "Content Selection", etc.

event_data: A custom data object that holds metadata for the user event. This might include information about a selection the user makes or the color of a button the user presses.

Usage Examples
await gumband.create_event(
    "Button Press", 
    { "color": "blue" }
)

await gumband.create_event(
    "Chapter Selection", 
    { 
        "chapter": "My First Chapter",
        "book": "My Book Title",
    }
)

end_interaction

end_interaction(event_data: dict) -> Promise<void>

Sends a user event to end the current interaction with Gumband.

event_data: A custom data object that holds metadata for the user event. This might include information about how the user ended the interaction.

Usage Example
await gumband.end_interaction({ "reason": "Survey Completed" })

send_email_notification

send_email_notification(message: str) -> Promise<void>

Sends an email notification to users subscribed to "Custom Email Notifications" in the Gumband UI.

message: The message to attach to your email notification.

Usage Example
await gumband.send_email_notification("Alert! The photo printer paper needs to be restocked soon.")

sync_content_files

sync_content_files() -> Promise<void>

Syncs the local and remote content files, pulling any missing remote files.

Usage Example
await gumband.sync_content_files()

Notification Events

Whenever an event occurs that your exhibit ought to know about, an event will be emitted from the Gumband class. These events can be a result of configuration changes made through the Gumband UI, a change in the exhibit's websocket connection to Gumband, and any errors that occur within the SDK.

READY

Emitted after the SDK successfully authenticates with Gumband, comes online, and is ready to make requests to Gumband.

Usage Example
gumband.on(SocketEventType.READY.value, on_ready)

async def on_ready(manifest):
    print(manifest)
    # {
    #     id: 1,                    //The exhibit ID
    #     siteId: 1,                //The project ID this exhibit belongs to
    #     name: 'Exhibit Name',     //The name of the exhibit in the Gumband UI 
    #     mqttPath: null,
    #     online: true,             //Whether the exhibit is online and connected to Gumband
    #     settingLists: [...],      //SettingsLists and their inner settings
    #     settingGroups: [...],     //SettingsGroups and their inner settings 
    #     settings: [...],          //All settings outside a list or group and their values
    #     statuses: [...],          //All statuses in the manifest and their values
    #     controls: [...],          //All controls in the manifest
    #     strapiContent: [...]  
    # }

CONTROL_RECEIVED

Emitted when a control is triggered, usually through the Exhibit/Controls tab in the Gumband UI.

Usage Example
gumband.on(SocketEventType.CONTROL_RECEIVED.value, on_control_received)

async def on_control_received(payload):
    print(payload)
    # {
    #   id: "reboot_computer",  //The id of the control defined in the manifest
    # }

    if payload.id == "reboot_computer":
        # trigger a reboot of the PC

SETTING_RECEIVED

Emitted when a setting value is changed, usually through the Exhibit/Settings tab in the Gumband UI.

Usage Example
gumband.on(SocketEventType.SETTING_RECEIVED.value, on_setting_received)

async def on_setting_received(payload):
    print(payload)
    # {
    #     id: 'setting_manifest_id',    //The id of the setting defined in the manifest
    #     value: 'new value'            //The current value of the setting
    # }

SETTING_LIST_RECEIVED

Emitted when a new settings list item is added or deleted, when the settings list items have their order changed, or when a setting value within a settings list item is changed. The payload is the new settings list with all of its items.

Usage Example
gumband.on(SocketEventType.SETTING_LIST_RECEIVED.value, on_setting_list_received)

async def on_setting_list_received(payload):
    print(payload)
    # {
    #     id: 'setting_list_manifest_id',   //The id of the SettingsList defined in the manifest
    #     value: [
    #         ...settingListItems           //The items that have been created within the SettingsList
    #     ]
    # }

SETTING_LIST_ITEM_DELETED

Emitted when a settings list item is deleted, usually through the Exhibit/Settings tab in the Gumband UI. The payload is the settings list item that was deleted.

Usage Example
gumband.on(SocketEventType.SETTING_LIST_ITEM_DELETED.value, on_setting_list_item_deleted)

async def on_setting_list_item_deleted(payload):
    print(payload)
    # {
    #   "id": "setting_list_manifest_id",   //The id of the SettingsList defined in the manifest
    #   "value": [
    #     {
    #       "id": "deleted_list_item_name", //The name of the SettingsList item the was deleted
    #       "value": [ ...listItemValues ]  //The settings within the item that was deleted
    #     }
    #   ]
    # }

EXHIBIT_ONLINE

Emitted when the SDK successfully authenticates with Gumband and comes online.

Usage Example
gumband.on(SocketEventType.EXHIBIT_ONLINE.value, on_exhibit_online)

async def on_exhibit_online():
    # no payload for the EXHIBIT_ONLINE event

EXHIBIT_OFFLINE

Emitted when the SDK loses its websocket connection with Gumband.

Usage Example
gumband.on(SocketEventType.EXHIBIT_OFFLINE.value, on_exhibit_offline)

async def on_exhibit_offline():
    # no payload for the EXHIBIT_OFFLINE event

FILE_UPLOADED

Emitted when a new file has been uploaded to Gumband, usually through the Exhibit/Files tab of the Gumband UI.

Usage Example
gumband.on(SocketEventType.FILE_UPLOADED.value, on_file_uploaded)

async def on_file_uploaded(payload):
    print(payload)
    
    # {
    #   file: 'uploadedFileName.png',           //The name of the uploaded file
    #   size: 7891,                             //The size of the uploaded file
    #   exhibitId: '1',                         //The id of the exhibit associated with this file
    #   lastUpdated: '2023-08-28T16:14:54.418Z' //The timestamp the file was uploaded
    # }

FILE_DELETED

Emitted when a file is deleted from Gumband, usually through the Exhibit/Files tab of the Gumband UI.

Usage Example
gumband.on(SocketEventType.FILE_DELETED.value, on_file_deleted)

async def on_file_deleted(payload):
    print(payload)
    
    # { 
    #   file: 'deletedFileName.png' //The name of the deleted file
    # }

ERROR

Emitted when any error is logged to the local logger.

Usage Example
gumband.on(SocketEventType.ERROR.value, on_error)

async def on_error(payload):
    print(payload)
    
    # This is an error message

Configuration Options​

connect​

get_manifest​

set_status​

get_status​

set_setting​

get_setting​

create_event​

end_interaction​

send_email_notification​

sync_content_files​

Notification Events​

READY​

CONTROL_RECEIVED​

SETTING_RECEIVED​

SETTING_LIST_RECEIVED​

SETTING_LIST_ITEM_DELETED​

EXHIBIT_ONLINE​

EXHIBIT_OFFLINE​

FILE_UPLOADED​

FILE_DELETED​

ERROR​