document.getElementById('tryBtn').addEventListener('click', e => {
embed.trigger((HostEvent.DownloadAsPng)
});
Events and app integration
ThoughtSpot supports a range of events that your app can listen to and respond to with appropriate actions. The embedded ThoughtSpot components emit events when they initialize and load, and when a user executes an action inside these components. The host application can also trigger events within the embedded ThoughtSpot objects, causing an alert or other action.
Embed eventsπ
Embed events are emitted by the embedded ThoughtSpot components and are part of the EmbedEvent
object. Embed events are emitted when ThoughtSpot components initialize and load, or when users interact with these components. For example, you can register an event handler to trigger EmbedEvent.Save
when a user clicks the Save action on the Answer page in the embedded UI. You can also define a listener for an EmbedEvent with a callback function to handle the event response via the .on(embedEvent, eventHandlerCallbackFunction)
format. For some of these action-triggered events, you can register event handlers to emit events when the corresponding action starts and ends.
For more information, see EmbedEvent.
Host eventsπ
Host events are triggered by the host application in which ThoughtSpot components are embedded. Host events use the .trigger()
method to send the event message to embedded ThoughtSpot components in the .trigger(hostEvent, data)
format. The host events are part of the HostEvent object; for example, HostEvent.SetVisibleVizs
.
To explore the host event functionality in the Playground, follow these steps:
-
Go to Develop > Visual Embed SDK > Playground.
-
Select the feature to embed, for example, Search.
-
Select the objects to load in the Playground.
-
In the event handler code, add a host event as shown in the following example:
-
Click Run.
-
Click Try Event to trigger the action.
The following video shows how to register HostEvent.RemoveColumn
and remove a column from the search query string using the Try button:
For more information, see HostEvent.
Import Events libraryπ
Import the event library from the Visual Embed SDK package.
import { EmbedEvent, HostEvent } from '@thoughtspot/visual-embed-sdk';
To trigger events on ThoughtSpot components embedded in a React app, import the useEmbedRef
hook.
import { LiveboardEmbed, useEmbedRef } from '@thoughtspot/visual-embed-sdk/react';
Common use casesπ
Handle load and errors for embedded componentsπ
A common workflow is to use an overlay div
element to hide the embed content until you know that SSO has completed, and the content is fully loaded. If an error occurs in the process, you may prefer to display your own custom message to the end user rather than showing embedded ThoughtSpot content in an error state.
Embed events fire at points within the loading process. The following events are related to the load process:
-
Init
Fires at the beginning of the loading process.
-
NoCookieAccess
Some browsers (Safari in particular) default to strict settings on cookie origins that prohibit the standard SSO process. This event fires if cookies are restricted by a userβs browser.
-
AuthExpire
Fires if SSO does not complete and if the ThoughtSpot session times out at some point. Listen to the
AuthExpire
event in the load process to determine when it is safe to show the ThoughtSpot content, and listen to it after loading to hide the ThoughtSpot login screen if the session expires for some reason. -
AuthInit
Fires when the SSO process is completed correctly. The event does not fire when an SSO process fails, instead
AuthExpire
fires in that situation. The logged-in user GUID is available in theAuthInit
event response. -
Error
Fires if any other error occurs in the Visual Embed SDK process. Does not fire for errors within the embedded ThoughtSpot content
-
Load
Fires as soon as the area for embedding is created, not when the content has begun or finished loading.
-
Data
Fires only on
SearchEmbed
components. Does not fire on aLiveboardEmbed
component. -
LiveboardRendered
Fires only on
LiveboardEmbed
components when the Liveboard or visualization container loads.
AuthExpire
and AuthInit
can be used together to determine if the SSO process is completed correctly. To determine if AuthExpire
is firing because SSO did not complete or if the ThoughtSpot session has timed out, you can set a variable to act as a flag to determine if SSO is completed. When AuthInit
fires, set the flag to true. You can also associate a callback function to AuthExpire
to look up the flag to determine which state change has caused the AuthExpire
event to fire. In the following example, the tsLoggedIn
flag is set to indicate the SSO login state.
// Instantiate class for embedding a Liveboard
const embed = new LiveboardEmbed("#thoughtspot-embed", {
liveboardId: '<Liveboard-guid>',
});
let tsLoggedIn = false;
embed
.on(EmbedEvent.Init, showLoader)
.on(EmbedEvent.NoCookieAccess, showCookieSettingsMsg)
.on(EmbedEvent.AuthInit, (response) => {
// Set that AuthInit has fired
tsLoggedIn = true;
// authInit returns object -> {type: 'authInit', data: {userGuid: <guid>} } }
let userGUID = response.data.userGuid;
})
.on(EmbedEvent.AuthExpire, (response) => {
// Handle if session dies while content shows
if (tsLoggedIn == true) {
tsSessionTimeoutCleanup();
} else {
// Display custom message if SSO issues
showSSOFailedMsg();
}
})
.on(EmbedEvent.Error, showGenericErrorMsg)
.on(EmbedEvent.LiveboardRendered, hideLoader)
.render()
Filters in embedded UIπ
Runtime filters can be set programmatically before loading the embedded ThoughtSpot content in the options
object set in the LiveboardEmbed
component constructor.
Runtime filters can be updated after load time by triggering the HostEvent.UpdateRuntimeFilters
event. You can build the filter UI in the embedding app, which triggers the UpdateRuntimeFilters
event when changed or with the click of an apply
button.
Filtering from selectionπ
Filtering from a selection on a chart or table can be implemented by combining the EmbedEvent.VizPointClick
or EmbedEvent.VizPointDoubleClick
events with the HostEvent.UpdateRuntimeFilters
event.
The callback function from the VizPointClick
event will need to read the response, parse out the attributes from the response that will be sent to the Runtime Filters, and then send the attributes and their target fields in the format used by UpdateRuntimeFilters
.
ThoughtSpot filters overviewπ
ThoughtSpot Liveboards have four levels of filters.
- Row-level security (RLS) rules
-
Tied to the logged-in user and their group memberships. Completely secure and cannot be altered by the logged-in user.
- Runtime filters
-
Set via the Visual Embed SDK or URL parameters. Runtime filters do not display as UI filter components.
- Answer filters
-
Established via the search definition, not visible as UI filter components on a Liveboard, but can be viewed in Explore or Edit modes.
- Liveboard filters
-
Visible as UI components at the top of a Liveboard, affecting all visualizations on the Liveboard.
Modify SearchEmbed behaviorπ
The hideResults
parameter in the options object of a SearchEmbed
constructor blocks the GO button from displaying the chart or table results. When this option is true, you can listen to the QueryChanged
event to perform actions based on the userβs interaction within the SearchEmbed
component.
SearchEmbed Eventsπ
There are several events that fire only on the SearchEmbed component:
-
DataSourceSelected
Fires when a change occurs in the data sources, including the initial load of the
SearchEmbed
component. Can be used to hide a loader screen. Return object contains an array of the selected column GUIDs (accessible usingLOGICAL_COLUMN
type within metadata REST API commands). -
QueryChanged
Fires when a change occurs in the search bar, including the initial load of the
SearchEmbed
component. The returned object includes adata.search
property with the TML search query from the search box.
Handle custom action eventsπ
If you have added a custom action set as a callback action, you must register an event handler to send data in a payload when the custom action is triggered:
searchEmbed.on(EmbedEvent.customAction, payload => {
const data = payload.data;
if (data.id === 'show-data') {
console.log('Custom Action event:', data.embedAnswerData);
}
})
liveboardEmbed.on(EmbedEvent.CustomAction, (payload) => {
if (payload.data.id === 'show-data') {
const showActionId = 'show-data';
if (payload.id === showActionId \|\| payload.data.id === showActionId) {
showData(payload);
}
})
Related resourcesπ
-
For a complete list of event types, see EmbedEvent and HostEvent SDK documentation.
-
For information about triggering events on React components, see Embed ThoughtSpot in a React app.