@thoughtspot/visual-embed-sdk
Version:
ThoughtSpot Embed SDK
249 lines (184 loc) • 7.63 kB
Markdown
<p align="center">
<img src="https://raw.githubusercontent.com/thoughtspot/visual-embed-sdk/main/static/doc-images/images/TS-Logo-black-no-bg.svg" width=120 align="center" alt="ThoughtSpot" />
</p>
<br/>
SDK to embed ThoughtSpot into your web apps. You need a ThoughtSpot account to use the SDK, [click here](https://www.thoughtspot.com/trial?tsref=trialtse) to start a trial.
* [Installation](
* [Live Playground](
* [Full API Reference](
* [Quick Start](
* [Embedded Search](
* [Embedded Liveboard & Visualization](
* [Embedded Full App](
* [Triggering and Listening to events](
* [React Components](
* [Search Component](
* [Triggering events on React components](
* [Contributing](
The SDK is compatible with ThoughtSpot SW version >= 7.1 and ThoughtSpot Cloud.
Install the Visual Embed SDK from [NPM](https://www.npmjs.com/package/@thoughtspot/visual-embed-sdk):
```
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,...
```js
// 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';
```
<br/>
Visit our [code playground](https://try-everywhere.thoughtspot.cloud/v2/#/everywhere). <br/><br/>
Start a [free trial](https://www.thoughtspot.com/trial?tsref=trialtse) on your own data.
<br/>
- Thoughtspot Embedded [Docs](https://developers.thoughtspot.com/docs/)
- Please visit our [API reference docs](https://developers.thoughtspot.com/docs/VisualEmbedSdk).
- Comprehensive [CodeSandbox](https://codesandbox.io/s/big-tse-react-demo-i4g9xi?file=/src/App.tsx)
<br/>
The ThoughtSpot Embed SDK allows you to embed the ThoughtSpot search experience,
liveboards, visualizations or the even full app version.
```js
// 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();
```
```js
// 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();
```
```js
// 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();
```
```js
// 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']);
});
```
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.
<br/><br/>
Checkout a comprehensive working demo [here](https://codesandbox.io/s/big-tse-react-demo-i4g9xi?file=/src/App.tsx)
```js
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}
/>
);
};
```
```jsx
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}
/>
);
};
```
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.
<br/>
<br/>
Visual-Embed-SDK, © ThoughtSpot, Inc. 2023