Embed ThoughtSpot

Table of Contents

Before you begin
Embed using SDK
- Import the embed package
Initialize the SDK
- Embed ThoughtSpot Component
Register events
Render the embedded object
Code sample
Embed in a React app
Related information

Based on your embedding requirements and integration setup, you can use one of the following methods:

Embed using Visual Embed SDK (Recommended)

ThoughtSpot Visual Embed SDK offers a JavaScript library that allows you to embed ThoughtSpot components in web pages. This section helps you get started with embedding a ThoughtSpot component in your app.
iFrame embedding without SDK

The following sections describe how to embed a ThoughtSpot component using Visual Embed SDK. For additional guidance refer to the Embedding fundamentals tutorial.

Before you begin🔗

Important

Adjust CORS and CSP settings

Before embedding ThoughtSpot in your app, check if your application domain is added to the CSP and CORS allowlist on the Develop > Customizations > Security Settings page.

If you encounter any errors when using the Visual Embed SDK components, verify the CORS and CSP settings.

Get Developer access

Only administrators and users with Developer privilege can access the Develop tab. Please have your administrator add any users who will be developing embedded solutions to a ThoughtSpot group with Has Developer privilege.

Embed using SDK🔗

The Visual Embed SDK is available for installation as a Node Package Manager (NPM) package. The latest version of the Visual Embed SDK is available at https://www.npmjs.com/package/@thoughtspot/visual-embed-sdk.

Import the embed package🔗

The SDK is written in TypeScript and is also provided both as ES Module (ESM) and Universal Module Definition (UMD) modules, allowing you to use it in a variety of environments. The SDK is written in TypeScript and is also provided both as ES Module (ESM) and Universal Module Definition (UMD) modules, allowing you to use it in a variety of environments.

Import one of the following modules into your app:

LiveboardEmbed
To embed a single visualization or a full Liveboard with multiple visualizations.
SpotterEmbed
To embed embed Spotter AI search and analytics.

AppEmbed
To embed full ThoughtSpot application experience or specific application pages.
SearchEmbed
To embed ThoughtSpot Search page with a pre-selected data source.
SearchBarEmbed
To embed only the ThoughtSpot Search bar and data panel.

Example🔗

// ESM via NPM
import * as TsEmbedSDK from '@thoughtspot/visual-embed-sdk';
// OR
import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk';

// NPM <script>
<script src="https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.js"></script>;
// Make the SDK available on global namespace window.tsembed

// ES6 from web
import {
    LiveboardEmbed,
    AuthType,
    init,
    EmbedEvent,
    HostEvent
} from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js';

Initialize the SDK🔗

After importing the package, specify the hostname or IP address of your ThoughtSpot application instance and the authentication type. For other supported authentication methods, see Authentication.

init({
    thoughtSpotHost: "https://<hostname>:<port>",
    authType: <AuthType>,
    ... // other authType dependent properties.
});

Embed ThoughtSpot Component🔗

Create an object instance and define object properties. This example shows the code sample for a Liveboard object:

const liveboardEmbed = new LiveboardEmbed(
    document.getElementById('ts-embed'),
    {
        frameParams: {
            width: '100%',
            height: '100%',
        },
        liveboardId: '<%=liveboardGUID%>',
    },
});

Register events🔗

Register events that your app can listen to and respond with appropriate actions. The following example registers LiveboardRendered and SetVisibleVizs events. The LiveboardRendered embed event is emitted when the embedding application renders the Liveboard and triggers the SetVisibleVizs event to show specific visualizations on the Liveboard.

liveboardEmbed.on(EmbedEvent.LiveboardRendered, () => {
    liveboardEmbed.trigger(HostEvent.SetVisibleVizs, ['viz1', 'viz2']);
});

Render the embedded object🔗

Render the embedded application.

liveboardEmbed.render();

Code sample🔗

import {
    LiveboardEmbed,
    AuthType,
    init,
    EmbedEvent,
    HostEvent
} from '@thoughtspot/visual-embed-sdk';

// Create a new LiveboardEmbed instance, targeting the DOM element with id 'container'.

const lb = new LiveboardEmbed('#container', {
    // Set the frame size to 100% width and height
    frameParams: {
        width: '100%',
        height: '100%',
    },
    liveboardId: '<%=liveboardGUID%>', // ID of the Liveboard
    runtimeFilters: [{
        columnName: 'Color',
        operator: RuntimeFilterOp.EQ,
        values: ['red'],
    }, ],
});

// [Optional]: Register an event listener for the LiveboardRendered event.
// This allows you to execute custom logic when the Liveboard has finished rendering.
lb.on(EmbedEvent.LiveboardRendered, (e) => {
    /* handler */
});

// Render the embedded Liveboard inside the specified container.
// This step is required to display the Liveboard in your application.
lb.render();

// Programmatically trigger a HostEvent to update runtime filters on the embedded Liveboard.
lb.trigger(HostEvent.UpdateRuntimeFilters, [{
    columnName: 'Color',
    operator: RuntimeFilterOp.EQ,
    values: ['amber'],
}, ]);

#container is a selector for the DOM node which the code assumes is already attached to DOM. The SDK will render the ThoughtSpot component inside this container element.

Embed in a React app🔗

ThoughtSpot provides React components for embedding Search, Liveboard, and the full ThoughtSpot application in a React app. The following code sample shows how to embed a Liveboard component in a React app:

// Import the LiveboardEmbed React component from the ThoughtSpot Visual Embed SDK
import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk/react';

const App = () => {
    // Create a ref to interact with the embedded Liveboard instance
    const embedRef = useEmbedRef();

    // Event handler called when the Liveboard has finished rendering
    const onLiveboardRendered = () => {
        // Trigger a HostEvent to update runtime filters on the embedded Liveboard
        // This filter sets the 'col1' column to only show rows where the value is 'val1'
        embedRef.current.trigger(HostEvent.UpdateRuntimeFilters, [
            {
                columnName: 'Color',
                operator: RuntimeFilterOp.EQ,
                values: ['amber'],
            },
        ]);
    };

    // Render the LiveboardEmbed component with the specified Liveboard ID and event handler
    return (
        <LiveboardEmbed
            ref={embedRef} // Attach the ref for programmatic control
            liveboardId="<liveboard-guid>" // The GUID of the Liveboard to embed
            onLiveboardRendered={onLiveboardRendered} // Register the event handler
        />
    );
};

For more information, see Embed ThoughtSpot in a React app.