# Embed SDK - Getting Started

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

# Embed SDK Webinar

# Setup

Before proceeding, make sure your Sisense version supports the Embed SDK. The SDK is supported with Sisense versions 8.0 or later. To make sure, navigate to http://localhost:8081/js/frame.js on your Sisense server - you should get a Javascript source file as a response.

# Configure CORS

To enable the Embed SDK you must enabling CORS. For that, please refer to the Sisense CORS documentation.

# 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

# 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="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)

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-frame')
});

// 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://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
    },
    // 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!");
});

# 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 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

# Additional References

• Developer playground: Embed SDK
• Webinar: Embed SDK
• Github: Embed SDK demo
• API Reference: Embed SDK