Get Started with embedding

Get Started with embedding

ThoughtSpot provides Visual Embed SDK to embed Search bar, Search page, Liveboard, visualizations, or the full ThoughtSpot experience in your web application or portal. 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.

Before you begin🔗

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

  • Enable Developer Portal access

    ThoughtSpot users can access Developer Portal via Develop tab in the UI.

    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.

Install the Visual Embed SDK🔗

The Visual Embed SDK is available for installation as a Node Package Manager (NPM) package. Make sure the NPM is installed in your environment.

The latest version of the Visual Embed SDK is available at https://www.npmjs.com/package/@thoughtspot/visual-embed-sdk.

To install the SDK from NPM, execute the following command:

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.

// 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,
} from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js';

Import one of the following modules into your app:

  • LiveboardEmbed
    Use the LiveboardEmbed component to embed a single visualization or a full Liveboard with multiple visualizations

    Embed a Liveboard

  • AppEmbed
    Use the AppEmbed library to embed full ThoughtSpot application in your app.

    Embed full ThoughtSpot application

  • SearchEmbed
    Use the SearchEmbed package to embed the ThoughtSpot search page with a pre-selected data source.

    Embed Search page

  • SearchBarEmbed
    Use the SearchBarEmbed component to embed only the ThoughtSpot Search bar and data panel.

    Embed Search bar

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.
});

Define the object instance and properties🔗

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🔗

Subscribe and listen to events triggered when the embedded object interacts with your app. 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,
    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🔗