Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@thoughtspot/visual-embed-sdk

thoughtspot115.6kThoughtSpot Development Tools End User License Agreement1.39.2TypeScript support: included

ThoughtSpot Embed SDK

thoughtspot, everywhere, embedded, embed, sdk, analytics

readme

ThoughtSpot


ThoughtSpot Visual Embed SDK
Coverage Status npm (scoped with tag) npm npm bundle size (scoped) Discord: ThoughtSpot

SDK to embed ThoughtSpot into your web apps. You need a ThoughtSpot account to use the SDK, click here to start a trial.

Installation

The SDK is compatible with ThoughtSpot SW version >= 7.1 and ThoughtSpot Cloud.

Install the Visual Embed SDK from NPM:

npm i @thoughtspot/visual-embed-sdk

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. For 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>;
// Makes 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';

Live Playground

Visit our code playground.

Start a free trial on your own data.


Full API Reference


Quick Start

The ThoughtSpot Embed SDK allows you to embed the ThoughtSpot search experience, liveboards, visualizations or the even full app version.

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

init({
    thoughtSpotHost: '<%=tshost%>',
    authType: AuthType.None,
});

const searchEmbed = new SearchEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
});

searchEmbed.render();

Embedded Liveboard & Visualization

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

init({
    thoughtSpotHost: '<%=tshost%>',
    authType: AuthType.None,
});

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

liveboardEmbed.render();

Embedded Full App

// NPM
import { AppEmbed, Page, AuthType, init } from '@thoughtspot/visual-embed-sdk';
// or ES6
// import { AppEmbed, AuthType, init } from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js';

init({
    thoughtSpotHost: '<%=tshost%>',
    authType: AuthType.None,
});

const appEmbed = new AppEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    pageId: Page.Data,
});

appEmbed.render();

Triggering and Listening to events

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

// .. Do init and create a liveboardEmbed object as above.

liveboardEmbed.render();

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

React Components

All the above flavors of embedding are also provided as React components for your convenience. The constructor options are passed as props and the event listeners can be attached using on<EventName> convention.

Checkout a comprehensive working demo here

Search Component

import { init } from '@thoughtspot/visual-embed-sdk';
import { SearchEmbed } from '@thoughtspot/visual-embed-sdk/react';

// If you are using Webpack 4 (which is the default when using create-react-app v4), you would need to import
// the React components using the below:
import { SearchEmbed } from '@thoughtspot/visual-embed-sdk/lib/src/react';

init({
    thoughtSpotHost: '<%=tshost%>',
    authType: AuthType.None,
});

const MyComponent = ({ dataSources }) => {
    const onCustomAction = (actionEvent) => {
        // Do something with actionEvent.
    };

    return (
        <SearchEmbed
            dataSources={dataSources}
            onCustomAction={onCustomAction}
        />
    );
};

Triggering events on React components (> version 1.9.2)

import { HostEvent } from '@thoughtspot/visual-embed-sdk';
import { LiveboardEmbed, useEmbedRef } from '@thoughtspot/visual-embed-sdk/react';

const MyComponent = () => {
    const embedRef = useEmbedRef();
    const onLiveboardRendered = () => {
        embedRef.current.trigger(HostEvent.SetVisibleVizs, ['viz1', 'viz2']);
    };

    return (
        <LiveboardEmbed
            ref={embedRef}
            liveboardId="<liveboard-guid>"
            onLiveboardRendered={onLiveboardRendered}
        />
    );
};

#

Contributing

Local dev server

How to run the local vite server to test out the sdk.

$ npm run build
$ npm run dev

Goto http://localhost:2343/local to check the output.

Look at local/index.html and local/index.ts for some starter code.



Visual-Embed-SDK, © ThoughtSpot, Inc. 2023

changelog

Changelog

Please find the comprehensive list of changes for ThoughtSpot releases and SDK here This project follows Semantic Versioning.

Unreleased

New Features

  • Set of new Host events to drive interactions on the embed programatically

1.14.1 (08-31-2022)

  • Fixed "not logged in" message showing up on "SearchEmbed" with AuthType.None.

1.14.0 (08-29-2022)

  • [AuthType.AuthServer] Now uses POST call to log the user in using the bearer token.
  • liveboardV2 flag on LiveboardEmbed to try out the LiveboardV2 experience.

1.13.0 (07-19-2022)

  • Release to support TS version 8.5.0.cl
  • Please check the full list of changes here

    1.12.1 (06-21-2022)

    Fixed

  • Search embed beta warning check for TS cloud releases

    1.12.0 (06-21-2022)

  • Release to support TS version 8.4.0.cl
  • Please check the full list of changes here

1.11.2 (06-10-2022)

Fixed

  • Typescript build that was affecting some Angular project configurations

1.11.1 (05-30-2022)

Fixed

  • Whitelabeling - new action for the ability to turn off TS specific error reporting by end users.

1.11.0 (05-20-2022)

  • Release to support TS version 8.3.0.cl
  • Please check the full list of changes here

1.10.4 (05-06-2022)

New Features

  • Config option detectCookieAccessSlow when doing Basic|AuthServer auth. Ref doc

1.10.3 (05-04-2022)

Fixed

  • logout method works consistently on multiple TS releases

1.10.2 (05-01-2022)

New features

  • Ability to configure redirectPath on the origin when using SSO auth. Ref doc

1.10.1 (05-01-2022)

New features

  • logout method exposed from the SDK. This can be used to log the user out. Ref doc

Updated

  • When login fails the user is presented with a Not logged in message, which is configurable using loginFailedMessage property on init. Ref doc
  • init now returns a event emitter which can be used to listen to Login failures and success. Ref doc

1.10.0 (04-22-2022)

  • Release to support TS version 8.2.0.cl
  • Please check the full list of changes here

1.9.5 (04-06-2022)

New Features

  • locale param to set Locale/language for the embedded view.

1.9.4 (04-06-2022)

Fixed

  • [React] className should be forwarded to the iframe container div.

1.9.3 (03-22-2022)

New Features

  • disableLoginRedirect option in EmbedConfig

1.9.2 (03-17-2022)

New Features

  • Ability to trigger events on React components
    • Added new useEmbedRef hook, check README for usage.

Fixed

  • Typings for on* event handlers for React components

1.9.1 (03-15-2022)

New Features

  • visibleVizs option in the LiveboardEmbed
  • LiveboardRendered new EmbedEvent emitted when a liveboard completes rendering.

1.9.0

  • Release to support TS version 8.1.0.cl
  • Please check the full list of changes here

1.8.1

Bug fix

  • authEndpoint in AuthServer authentication scheme was failing because of a missing await.

1.8.0

Breaking Changes

  • autoLogin option in init method is now by default false instead of true.

New Features

  • init method now returns the authPromise which resolves when auth is complete.

1.7.0 (and earlier)

  • Please check the full list of changes here