Listening events

Access dashboard settings via event handlers

Overview

An event fires at dashboard load time or when a specific dashboard action occurs. Register a handler with ubidots.on() — the callback receives the event argument when the event fires.

Registering for an event

ubidots.on('<event>', function(payload) {
    // your logic here
});

Available events

Event	Triggered when	Argument
v2:auth:token	At dashboard load time, when the user's API token is retrieved.	string
v2:auth:jwt	At dashboard load time, when the user's JWT token is retrieved.	string
v2:auth:*	At dashboard load time, when either the API token or JWT is retrieved.	string
v2:dashboard:settings:daterange	The dashboard's date range is changed via the GUI or programmatically.	Timeframe
v2:dashboard:settings:rt	The dashboard's real-time setting is toggled via the GUI or programmatically.	boolean
v2:dashboard:settings:refreshed	A user clicks the refresh button in the dashboard.	—
v2:dashboard:settings:filters	The dashboard's filters configuration is changed.	Filters
v2:dashboard:devices:self	At dashboard load time, with all devices associated with the dashboard.	Device[]
v2:dashboard:devices:selected	The selected device in a dynamic dashboard is changed via the GUI or programmatically.	Device[]
v2:dashboard:self	At dashboard load time, when the dashboard metadata is retrieved.	Dashboard
v2:dashboard:*	Any of the above dashboard events fire (catch-all).	varies (same as the specific event)
v2:widget:ready	At dashboard load time, after all other events have been triggered.	—

v2:auth:* and v2:dashboard:* are the only supported wildcards. Patterns like v2:dashboard:settings:* are not valid — the callback is silently discarded and never fires.

Payload reference

Device object

Delivered by v2:dashboard:devices:self (all dashboard devices) and v2:dashboard:devices:selected (currently selected devices). Both events always deliver an array, even for a single selection.

{
    "url": "https://industrial.ubidots.com/api/v2.0/devices/<device-id>",
    "id": "<device-id>",
    "label": "<device-label>",
    "name": "<device-name>",
    "description": "",
    "createdAt": "<ISO-timestamp>",
    "lastActivity": <unix-timestamp-ms>
}

Timeframe object

Delivered by v2:dashboard:settings:daterange. Both values are Unix timestamps in milliseconds.

{
    "start": 1710000000000,
    "end": 1710086400000
}

Filters array

Delivered by v2:dashboard:settings:filters. Each outer array is a filter group (OR logic between groups); each inner array contains the conditions for that group (AND logic within a group).

[
    [
        { "type": "value", "value": "60", "variables": "~temperature", "lookup": "lte", "negate": false },
        { "type": "value", "value": "30", "variables": "~temperature", "lookup": "gte", "negate": false }
    ],
    [
        { "type": "value", "value": "60", "variables": "~humidity", "lookup": "lte", "negate": false }
    ]
]

Dashboard object

Delivered by v2:dashboard:self.

{
    "id": "<dashboard-id>",
    "label": "<dashboard-label>",
    "name": "<dashboard-name>",
    "context": { "dashboardType": "<type>" },
    "widgetsNumber": 4,
    "isEditable": true,
    "timeframe": {}
}

Class properties

Each event also populates a property on the ubidots instance. After v2:widget:ready fires, all properties are set and can be read synchronously — no handler needed.

Property	Populated by
ubidots.token	v2:auth:token
ubidots.jwtToken	v2:auth:jwt
ubidots.dashboardDateRange	v2:dashboard:settings:daterange
ubidots.realTime	v2:dashboard:settings:rt
ubidots.selectedFilters	v2:dashboard:settings:filters
ubidots.dashboardDevices	v2:dashboard:devices:self
ubidots.selectedDevices	v2:dashboard:devices:selected
ubidots.dashboardObject	v2:dashboard:self

Examples

Fetch device data whenever the selection changes

ubidots.on('v2:dashboard:devices:selected', function(devices) {
    const device = devices[0];
    fetch('https://industrial.api.ubidots.com/api/v1.6/devices/' + device.label + '/', {
        headers: ubidots.getHeaders()
    })
    .then(res => res.json())
    .then(data => renderWidget(data));
});

Sync a custom date picker with the dashboard

ubidots.on('v2:dashboard:settings:daterange', function(timeframe) {
    myDatePicker.setRange(
        new Date(timeframe.start),
        new Date(timeframe.end)
    );
});

Gate rendering on ready, then use token for API calls

ubidots.on('v2:widget:ready', function() {
    // All load-time events have fired — safe to read any property
    const headers = ubidots.getHeaders();
    const device  = ubidots.selectedDevices[0];
    loadChartData(device, headers);
});