Skip to content

getting-started.adoc

Latest commit

 

History

History
251 lines (195 loc) · 8.02 KB

getting-started.adoc

File metadata and controls

251 lines (195 loc) · 8.02 KB

Get Started with embedding

Table of Contents

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

  • xref:embed-without-sdk.adoc[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 page

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.