# Sisense Embed SDK Reference

Feature Availability

The Embed SDK is available on:

Sisense for Windows 8.1 or newer
Sisense for Linux L8.2.1 or newer

Some features in this reference are only available from Sisense version 8.1.1/L8.2.1 and higher - they are marked with the 8.1.1 badge

The Sisense Embed SDK is a Javascript library used for embedding Sisense Dashboards into web applications and facilitating the interaction between the host page and the embedded dashboard.

# Using the SDK

# Prerequisites

Make sure to read the Embed SDK documentation.
Ensure CORS is enabled on your Sisense web server.

# Importing the SDK

The SDK is bundled with the Sisense Web Server starting with Sisense v8.1; To use it on your web page or application, follow these steps:

Include the SDK file from your Sisense Web Server:
```
<script src="http://1.2.3.4:8081/js/frame.js"></script>
```
(Replace 1.2.3.4 with the IP or DNS address of your Sisense Web Server)
Import the module:
```
const { SisenseFrame, enums } = window['sisense.embed'];
```
(enums is optional, and contains values for different options in the API)

# SisenseFrame Class

Main SDK Entry point - An instance of this class represents a single Sisense embedded iFrame on the host page, and provides the API for interacting with the embedded Sisense application.

The SDK can either wrap an existing iFrame element by passing the element property to the constructor, or generate an iFrame element automatically into any DOM element provided as the container argument of render().

Notes:

Application related methods such as getUser are contained under the app property. These are methods that relate to the entire Sisense application, regardless of the frame's current state.
Dashboard related methods such as applyFilters are contained under the dashboard property. These are methods that relate to the currently Dashboard loaded in the iFrame and to navigation between dashboards.
Each of the above objects (app and dashboard) have their own on and off methods to subscribe to events in either the global application or dashboard contexts, and each has specific supported events.

# Constructor

new SisenseFrame(init)

Create a new instance of SisenseFrame to interact with a Sisense iFrame-embedded application.

Name	Type	Description
init	`init`	Initial configuration for the frame

# Properties

Note: The properties below will only be available once the render() method was called.

Property	Type	Description
`id`	`string`	iFrame element's id
`url`	`string`	iFrame base URL
`element`	`HTMLElement`	iFrame DOM element

# Methods

# render

render([container], [hidden]) → Promise<null>

Create the iFrame according to current settings.

If an iFrame DOM element was provided in the constructor via the element property, container is optional and can be left as undefined/null; Otherwise, a DOM element is required, into which the iFrame element will be rendered.

Parameters

Name	Type	Default	Description
[container]	`DOMElement`		A container DOM element to render the iFrame into
[hidden]	`boolean`	`false`	Whether the iFrame should be rendered in hidden mode

Returns

A Promise that resolves with no data when the iFrame element has been rendered.

# show

show()

Show the iFrame element.

Parameters

N/A

Returns

N/A

# hide

hide()

Hide the iFrame element.

Parameters

N/A

Returns

N/A

# getSettings

getSettings() → uiSettings

Get the current UI settings for the iFrame.

Parameters

N/A

Returns

A uiSettings type object

# updateSettings

updateSettings(settings) → Promise

Update the frame's UI settings.

Parameters

Name	Type	Description
settings	`uiSettings`	UI settings to apply to the iFrame

Returns

A Promise that resolves with no data when the new settings have been applied

# getState

getState() → frameState

Get the current state of the frame, with information on what is currently displayed within it.

Parameters

N/A

Returns

A frameState type object

# getSize

getSize() → Promise<sizingInfo>

Get frame content sizing information

Parameters

N/A

Returns

A Promise that resolves with a sizingInfo object.

# app.on

app.on(eventName, eventHandler)

Subscribe a handler to an application event.

Parameters

Name	Type	Description
eventName	`string`	Name of event to subsctibe to ¹
eventHandler	`function`	Event handler function

# ¹ Supported events:

"sisenseapploaded"

Returns

N/A

# app.off

app.off(eventName, eventHandler)

Un-subscribe a handler from an application event. The same event handler function must be passed as the eventHandler argument.

Parameters

Name	Type	Description
eventName	`string`	Name of event to unsubsctibe from ¹
eventHandler	`function`	Event handler function to unsubsctibe

# ¹ Supported events:

"sisenseapploaded"

Returns

N/A

# app.getInfo

app.getInfo() → Promise.<AppInfo>

Get information about the Sisense application currently displayed in the iFrame.

Parameters

N/A

Returns

A Promise that resolves to the AppInfo type

# app.getUser

app.getUser() → Promise.<UserInfo>

Get information about the current user logged in to the Sisense application currently displayed in the iFrame.

Parameters

N/A

Returns

A Promise that resolves to the UserInfo type

# app.logout

app.logout()

Log out from Sisense.

The iFrame will automatically redirect to the login page, hence usually this will be called before the host page is navigated elsewhere or together with the hide() method to avoid showing the login page to the user.

Parameters

N/A

Returns

N/A

# dashboard.on

dashboard.on(eventName, eventHandler) → string

Subscribe a handler to a dashboard event.

Parameters

Name	Type	Description
eventName	`string`	Name of event to subsctibe to ¹
eventHandler	`function`	Event handler function

Returns

N/A

# dashboard.off

dashboard.off(eventName, eventHandler)

Un-subscribe a handler from a dashboard event. The same event handler function must be passed as the eventHandler argument.

Parameters

Name	Type	Description
eventName	`string`	Name of event to unsubsctibe from ¹
eventHandler	`function`	Event handler function to unsubscribe

# ¹ Supported Events

"dashboardloaded"
"dashboardunloaded"
"dashboardfilterschanged"
"dashboardrefreshed"
"dashboardstylechanged"
"dashboardwidgetadded"
"sizechanged"

Returns

N/A

# dashboard.open

dashboard.open(dashboardId, [editMode]) → Promise.<DashboardInfo>

Navigate the frame to a dashboard by the dashboard's OID. Calling this may trigger both dashboardunloaded and then dashboardloaded events.

Parameters

Name	Type	Default	Description
dashboardId	`string`		OID of dashboard to open
[editMode]	`booean`	`false`	Should dashboard be shown in edit mode

Returns

A Promise that resolves to the <DashboardInfo> type once the new dashboard is loaded

# dashboard.getCurrent

dashboard.getCurrent() → Promise.<DashboardInfo>

Get information about the current dashboard displayed in the iFrame, including a list of filters applied to it. If no dashboard is being displayed, the Promise will be rejected.

Parameters

N/A

Returns

A Promise that resolves to the <DashboardInfo> type

# dashboard.applyFilters

dashboard.applyFilters(filters, persist) → Promise.<Array.<Object>>

Apply (add or update) one or more filters to the current dashboard. If a filter already exists for the same dimension (field), it will be replaced. By default, Filter changes will not persist after refresh/reload and will not affect other users viewing the same dashboard, unless a true value is passed as the persist argument.

Parameters

Name	Type	Description
filters	`Array.<DashboardFilter>`	An array of filters to apply to the dashboard.
persist	`boolean`	Should the filter change be persisted.

Returns

Promise.<Array.<Object>> - An array containing all currently applied filters, after the operation is complete

# dashboard.removeFilters

dashboard.removeFilters(filters, persist) → Promise.<Array.<Object>>

Remove one or more filters from the current dashboard. Filters are matched using the dimension (field) name, so it is sufficient to provide just the jaql.dim property without the actual filter details to remove. By default, Filter changes will not persist after refresh/reload and will not affect other users viewing the same dashboard, unless a true value is passed as the persist argument.

Parameters

Name	Type	Description
filters	`Array.<DashboardFilter>`	An array of filters to remove from the dashboard.
persist	`boolean`	Should the filter change be persisted.

Returns

Promise.<Array.<Object>> - An array containing all currently applied filters, after the operation is complete

# dashboard.export

dashboard.export([mode]) → Promise

Trigger a dashboard export process - this command will open the export UI modal window within the iFrame, where the user can configure the export and download it.

Parameters

Name	Type	Default	Description
[mode]	`string`	`"pdf"`	Either `"pdf"` or `"png"` ¹

¹ Represented by enums.ExportMode.PDF and enums.ExportMode.PNG

Returns

A Promise that resolves with no data when the user closed the export window

widget.on(eventName, eventHandler) → string 8.1.1

Subscribe a handler to a widget event.

Parameters

Name	Type	Description
eventName	`string`	Name of event to subsctibe to ¹
eventHandler	`function`	Event handler function

# ¹ Supported Events

"widgetready"
"widgetloaded"
"widgetunloaded"
"widgetchanged"
"widgetsave"

Returns

N/A

widget.off(eventName, eventHandler) 8.1.1

Un-subscribe a handler from a widget event. The same event handler function must be passed as the eventHandler argument.

Parameters

Name	Type	Description
eventName	`string`	Name of event to unsubsctibe from ¹
eventHandler	`function`	Event handler function to unsubscribe

# ¹ Supported Events

"widgetready"
"widgetloaded"
"widgetunloaded"
"widgetchanged"
"widgetsave"

Returns

N/A

widget.open(dashboardId, widgetId, [editMode]) → Promise WidgetInfo 8.1.1

Navigate the frame to a widget by the dashboard and widget's OID. Calling this may trigger both widgetloaded and then widgetunloaded events.

Parameters

Name	Type	Default	Description
dashboardId	`string`		OID of dashboard containing the widget
widgetId	`string`		OID of widget to open
[editMode]	`booean`	`false`	Should dashboard be shown in edit mode

Returns

A Promise that resolves to the WidgetInfo type once the new dashboard is loaded

widget.getCurrent() → Promise.WidgetInfo 8.1.1

Get information about the current widget displayed in the iFrame. If no widget is being displayed, the Promise will be rejected.

Parameters

N/A

Returns

A Promise that resolves to the WidgetInfo type

widget.save([returnToDashboard]) → Promise.WidgetInfo 8.1.1

Applies changes to the widget, same as the "Apply" UI button would do, for cases when it is not visible. By default will keep the frame showing the widget. If true value is passed as the first argument, will automatically navigate back to the dashboard. Calling this may trigger both widgetsave and then widgetunloaded events.

Parameters

Name	Type	Default	Description
[returnToDashboard]	`booean`	`false`	Should dashboard be shown after save

Returns

A Promise that resolves to the WidgetInfo type once the widget is saved

# Events

# "sisenseapploaded"

Application Loaded event will fire when the Sisense application is loaded in the iFrame. At this point, app.getUser() and app.getInfo() become available.

Use constant enums.ApplicationEventType.LOADED.

Can only be used with app.on()/app.off()

Name	Type	Default	Description
eventName	`string`	`"sisenseapploaded"`	Event name