Embed SDK - Getting Started

Feature Availability

The Embed SDK is available on:

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

What is Sisense Embed SDK

The Embed SDK is a suite of JavaScript APIs delivered as a JavaScript library for consumption by the host app.
As an abstracted embedded interface that wraps an iFrame element, it comes packed with features to programmatically:

• Render a Sisense iFrame element or hook to an existing one
• Subscribe to various events fired within Sisense
• Execute commands like adding/removing filters or exporting dashboards
• Access information about the state of the Sisense application within the iFrame

The Embed SDK expands the basic capabilities of iFrames by utilizing postMessage communication between Sisense and the host page.
This technique is commonly used for basic integration, but the SDK takes out all the hassle and risk involved in manually implementing this, significantly speeding up development/integration.

TIP

A full API reference for all of the SDK's capabilities can be found in the Sisense Embed SDK Reference

A demo application is available on Sisense's GitHub account (opens new window)

Embed SDK Webinar

Setup

SameSite Cookie Policy

Some browsers, such as Chrome 80 (and newer), have implemented stricter policies regarding cookies that affect embedding.

For an embedded application to work in these browsers, SSL must be enabled and some additional configuration must be done in Sisense.

Please refer to Product Documentation: Security Settings (opens new window)

Configure CORS

To enable the Embed SDK you must enabling CORS. For that, please refer to the Sisense CORS documentation. (opens new window)

Configure SSO

To avoid showing the Sisense login page in the iFrame and provide a smooth user experience, you should configure SSO so that your users are automatically authenticated to Sisense allowing the iFrame to load dashboards immediately.

With SSO, you will use your host application or an external service as the identity provider, telling Sisense which user is trying to access it.

For more information, please refer to the Sisense SSO documentation (opens new window)

Import the SDK library

To use the Embed SDK, you will have to include the SDK JavaScript library in your host page using a <script> HTML tag:

<script src="https://example.com/js/frame.js"></script>

(Replace https://example.com with the IP or DNS address of your Sisense Web Server)

And then import the SisenseFrame class from the SDK:

const { SisenseFrame, enums } = window['sisense.embed'];

Note that enums is optional, and contains values for different options in the SDK such as event names.

Creating an instance of SisenseFrame

Each iFrame containing the Sisense application on your host page will be represented by an instance of the SisenseFrame class imported from the SDK.

You can either attach the instance to an existing iFrame element, or provide a container element and the SDK will create an iFrame for you.

Attaching to an existing iFrame element

You will need an existing iFrame element on your page, such as:

<iframe id="sisense-iframe"></iframe>

You will also need:

• The URL of your Sisense application, such as https://sisense.myapp.com:8081
• The OID of the dashboard you would like to open initially, such as: 5d39916c17b58f235cdae1b4

Create an instance of the SisenseFrame class:

// Create an instance of SisenseFrame
const sisenseFrame = new SisenseFrame({
    // Sisense application URL, including protocol and port if required
    url: 'https://sisense.myapp.com:8081',
    // OID of dashboard to load initially
    dashboard: '5d39916c17b58f235cdae1b4',
    // Which panels to show in the iFrame
    settings: {
        showToolbar: false,
        showLeftPane: false,
        showRightPane: false
    },
    // Existing iFrame DOM element
    element: document.getElementById('sisense-iframe')
});

// Calling render() will apply the above configuration to the existing iFrame element
sisenseFrame.render().then(() => {
    console.log("Sisense iFrame ready!");
});

Automatically create an iFrame element

You will need an existing DOM element on your page to render the iFrame into, such as a DIV:

<div id="sisense-container"></div>

You will also need:

• The URL of your Sisense application, such as https://sisense.myapp.com:8081
• The OID of the dashboard you would like to open initially, such as: 5d39916c17b58f235cdae1b4
• Optionally, an ID you would like the automatically generated iFrame element to have, such as 'sisense-iframe'

Create an instance of the SisenseFrame class and render it:

// Create an instance of SisenseFrame
const sisenseFrame = new SisenseFrame({
    // Sisense application URL, including protocol and port if required
    url: 'https://example.com',
    // OID of dashboard to load initially
    dashboard: '5d39916c17b58f235cdae1b4',
    // Which panels to show in the iFrame
    settings: {
        showToolbar: false,
        showLeftPane: false,
        showRightPane: false
    },
    // Optional ID for the iFrame element
    id: 'sisense-iframe'
});

// Calling render(container) will create an iFrame element within the container provided and apply the above configuration to it
sisenseFrame.render(document.getElementById('sisense-container')).then(() => {
    console.log("Sisense iFrame ready!");
});

Using volatile mode L2022.2

When a user interacts with the dashboard embedded using Embed SDK, such as when modifying filters, these changes are saved to the Sisense Application Database and are thus persisted. The user will see the changes upon reload, or even when logging in from a different machine.

From version L2022.2, Embed SDK also supports "volatile mode", where changes are not persisted and will only apply while the user is viewing the page. When volatile mode is used, refreshing the page will result in the dashboard loading in it's original state, before any changes made by the user.

To use volatile mode, pass volatile: true to the Embed SDK constructor:

// Create an instance of SisenseFrame
const sisenseFrame = new SisenseFrame({
    // Sisense application URL, including protocol and port if required
    url: 'https://example.com',
    // OID of dashboard to load initially
    dashboard: '5d39916c17b58f235cdae1b4',
    // Use volatile mode:
    volatile: true
});

Volatile Mode vs Edit Mode

Please note - "edit mode" for dashboards and widgets is not compatible with volatile mode (as edit mode relies on storing user changes).
When configuring the Embed SDK with volatile: true, the editMode parameter will be ignored.

Using Web Access Tokens L2021.10

In Sisense for Linux versions L2021.10 or newer, you can use Web Access Tokens together with EmbedSDK as an alternative to standard authentication methods such as SSO.

Web Access Token

For more information, please refer to the Web Access Token documentation (opens new window)

For embedding with EmbedSDK, the WAT is passed as an argument to the SDK upon initiation. For example:

const sisenseFrame = new SisenseFrame({
    // Sisense application URL, including protocol and port if required
    url: 'https://example.com:30845',
    // Web access token:
    wat: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
    // OID of dashboard to load initially
    dashboard: '5d39916c17b58f235cdae1b4',
    // Which panels to show in the iFrame
    settings: {
        showToolbar: false,
        showLeftPane: false,
        showRightPane: false
    },
    // Existing iFrame DOM element
    element: document.getElementById('sisense-iframe')
});

Interacting with the iFrame and Sisense application

All commands available in the Embed SDK work asynchronously and return JavaScript Promise objects that resolve when the operation is complete.

Additionally, timing your code execution correctly is enabled by using not just the promises of actions, but also various events that indicate a change in the iFrame's state, such as "dashboardloaded".

For example:

// Do something as soon as the iFrame is rendered
sisenseFrame.render(frameContainerElement[0]).then(() => {
    console.log("iframe element rendered!");
});
	
// Do something when a dashboard is loaded
sisenseFrame.dashboard.on(enums.DashboardEventType.LOADED, (args) => {
    console.log("Dashboard " + args.dashboard.oid + " loaded!");
});

Configuring the UI panels

Whether during the creation of the iFrame (via the constructor) or later using the updateSettings() method, you can configure which panels are shown by passing in the following configuration:

{
    showToolbar: false,
    showLeftPane: false,
    showRightPane: false
}

For example:

// Update UI settings
sisenseFrame.updateSettings({
    showToolbar: false,
    showLeftPane: false,
    showRightPane: false
}).then(() => {
    // Resolves when the settings have been applied
    console.log("New settings applied!");
})

Getting information

You can retrieve information from the Sisense application, such as information about the currently logged-in user or the currently shown dashboard.

For example:

// Get information about the current user
sisenseFrame.app.getUser().then((user) => {
    // Reflect some of this information in the host page UI
    document.getElementById('sisense-username').innerText = user.username;
});

// Get information about the current dashboard
sisenseFrame.dashboard.getCurrent().then((dashboard) => {
    // Reflect some of this information in the host page UI
    document.getElementById('dashboard-name').innerText = dashboard.title;
});

Events

You can subscribe to events fired by the Sisense application and react to them on your host page. You can also unsubscribe handlers from events.

For example:

// Define an event handler
function dashboardLoadedHandler(args) {
    console.log("Dashboard " + args.dashboard.oid + " loaded!");
}

// Subscribe to the dashboard loaded event
sisenseFrame.dashboard.on(enums.DashboardEventType.LOADED, dashboardLoadedHandler);

// Unsubscribe the handler from the event
sisenseFrame.dashboard.off(enums.DashboardEventType.LOADED, dashboardLoadedHandler);

Manipulating filters

You can add, replace and remove filters from the dashboard loaded in the iFrame using the Embed SDK's functions .dashboard.applyFilters() and .dashboard.removeFilters()

To work with dashboard filters, you will need to be familiar with the Sisense JAQL (JSON Analytical Query Language) syntax

To set filters, pass one or more filter objects to the applyFilters function. Existing filters on the same dimensions will be replaced, and the rest will be added. For example:

let filter = {
    "jaql" : {
        "title": "Country",
        "dim" : "[Country.Country]",
        "datatype": "text",
        "filter" : {
            "startsWith" : "a"
        }
    }
};
sisenseFrame.dashboard.applyFilters(filter);

You can also pass in an array of filters:

let filters = [
    {
        "jaql" :  {
            "title" : "Country",
            "dim" : "[Country.Country]",
            "datatype" : "text",
            "filter" : {
                "startsWith" : "a"
            }
        }
    },
    {
        "jaql" : {
            "title" : "Product",
            "dim" : "[Products.Name]",
            "datatype" : "text",
            "filter" : {
                "members": ["Laptop"]
            }
        }
    }
];
sisenseFrame.dashboard.applyFilters(filters);

To remove filters, pass one or more filters to the removeFilters function. It is sufficient to provide just the dimension name. For example:

sisenseFrame.dashboard.removeFilters({
    "jaql": {
        "dim": "[Sales.PurchaseDate (Calendar)]",
        "level": "days"
    }
});

Calling the applyFilters and removeFilters as described above will make volatile (temporary) changes to the dashboard filters - they will not persist once you refresh the page, and will not be seen by other users accessing the same dashboard.

To persist the filter changes, pass the optional persist boolean parameter, like so:

sisenseFrame.dashboard.applyFilters(filters, true);
sisenseFrame.dashboard.removeFilters(filters, true);

Note that for Date dimensions, the dimension is identified by both name and level, so both must be passed to add/remove a filter

Starting from version L2022.1 you can also use dashboard.clearFilters(persist) to remove all dashboard filters at once:

sisenseFrame.dashboard.clearFilters(true);

Working with UI Themes L2021.3

As part of the UI Customization & Themes (opens new window) feature available on Sisense for Linux L2021.3 or newer, you can apply any existing theme to the embedded Sisense UI using the desired theme's oid.

To get the available theme oids, you can use the

GET /api/v1/themes

REST API endpoint.

This oid can then be used in two ways:

Setting an initial theme

To predefine a theme before the embedded dashboard is loaded, specify the theme property as part of the EmbedSDK init object passed to the constructor when initializing the SDK:

var sisenseFrame = new SisenseFrame({
    url: 'https://example.com',
    dashboard: '5d39916c17b58f235cdae1b4',
    theme: '605b633dc24bb7001ae42fbb'
});

Setting a theme dynamically

To apply a theme dynamically at any time after initialization, use the oid as a parameter for the app.setTheme(themeOid) method of the SisenseFrame Class, which will apply the theme to the embedded Sisense application:

sisenseFrame.app.setTheme('605b633dc24bb7001ae42fbb').then(function() {
    console.log('new theme applied');
});

You can also clear the set theme using app.clearTheme() which will revert the UI to the user's default theme.