Embed ThoughtSpot

Embed ThoughtSpot

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.

There is also a hands-on embedding fundamentals tutorial available.

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.

To get started with embedding, install the SDK:

npm install @thoughtspot/visual-embed-sdk

Import 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.

Import one of the following modules into your app:

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';

const lb = new LiveboardEmbed('#container', {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    liveboardId: '<%=liveboardGUID%>',
    runtimeFilters: [],
});
// [Optional]: Register event listeners.
lb.on(EmbedEvent.LiveboardRendered, (e) => {
    /* handler */
});

// Do not forget to call render.
lb.render();

// [Optional]: Trigger events on the lb
lb.trigger(HostEvent.UpdateRuntimeFilters, [
    {
        columnName: 'col1',
        operator: RuntimeFilterOp.EQ,
        values: ['val1'],
    },
]);

#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 { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk/react';

const App = () => {
    const embedRef = useEmbedRef();
    const onLiveboardRendered = () => {
        embedRef.current.trigger(HostEvent.UpdateRuntimeFilters, [
            {
                columnName: 'col1',
                operator: RuntimeFilterOp.EQ,
                values: ['val1'],
            },
        ]);
    };
    return (
        <LiveboardEmbed
            ref={embedRef}
            liveboardId="<liveboard-guid>"
            onLiveboardRendered={onLiveboardRendered}
        />
    );
};

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

Related information🔗