Application Embedding (Dashboards)

IMPORTANT: This document is specific to Sigma dashboards. To learn about this topic for Sigma’s new Workbooks feature, please visit Application Embedding (Workbooks).

Sigma’s application embedding feature will allow you to securely display your interactive dashboards and visualizations in other applications without your users needing to authenticate through Sigma. Your embedded data will update in real time with Sigma, as it responds to new data from your warehouse.

To implement an embed, you will use an embed secret, custom session durations, a server side generated embed URL, along with additional custom parameters.

To learn more about embedding in general and explore all our two other embedding options, visit Dashboard Embedding: An Overview.

Summary of Content

Requirements
Embed Security
      Who Can See my Data?
Creating an Application Embed
      High Level Overview
      Generating an Embed Secret
      Creating the Embed Path
      Adding the Embed to your Application
            Creating the Embed API
            Fetching and Rendering the Embed URL
            Node.JS Example
Dashboard Controls in Embeds
Javascript Events
Related Resources

Requirements

Embed Security

Application embedding is the most complex of Sigma’s three embedded analytics options. An admin generated embed secret, limited session durations, and server-side code in your application, all contribute to your data’s security. 

Application Embeds are made possible by the creation of a unique and encrypted embed URL pointing to the dashboard or visualization you wish to display. This URL is generated on the server side of your application, accessed through the API you set up,  and rendered client side in an html iframe element.

When you create the API to generate your embed URL you can specify parameters that define what viewers will see and how they can interact with your embed.

Each API generated URL can only be used once.

Who Can See my Data?

Anyone with the embed URL will have access to view the embedded dashboard or visualization. However, access to a Sigma embed will not allow anyone to access additional data in Sigma without a Sigma account for your organization and proper permissions on the dashboard.

Creating an Application Embed

To create an application embed, you will need to complete a series of steps in Sigma and your non-Sigma application. This requires implementation of client and server-side code.

High Level Overview

  1. Create an embed secret in your Sigma Admin Portal.
  2. Create an embed path for the dashboard.
  3. Add an API to your application that generates a secure embed URL.
  4. Call the new API from your application’s client, sending the dashboard generated embed path as a parameter. The server will respond with an embed URL. This can then be passed to an iframe element in your client’s html.

 

Generating an Embed Secret

In order to create an application embed, your Sigma organization will need an embed secret. This secret will be encrypted in your embed URLs and used to ensure your application embed URLs are valid (see Creating the Embed API).

You cannot look up your organizations existing embed secret after it has been created. If you lose your embed secret, you will be able to regenerate a new one at any time. However, your existing embeds will be rendered invalid until they are updated with the new secret.

  1. Open your Admin Portal by selecting ‘Administration’ in the user menu at the top right of your screen.
  2. Select the Account page from the left hand panel.
    Screen_Shot_2020-10-29_at_8.35.20_AM.png
  3. Under the Embedding section, click Add.
  4. Copy the Embed Secret from the modal and store it in a secure location.
    Note: You will be able to view this key only once.
    Screen_Shot_2020-08-26_at_11.12.56_AM.png

 

Creating the Embed Path

An embed path is a URL that points to the dashboard or dashboard visualization that you are embedding. This URL can be created from your dashboards Embed Dashboard modal. It will later be passed to your application’s API for the generation of the embed URL (see Adding the Embed to your Application).

  1. Open the dashboard in Sigma. 
  2. If the dashboard is in Edit mode, click the Publish button. A dashboard must be published to create or manage embeds.
  3. Click the ••• menu icon in the Dashboard header.
  4. Select Embed Options from the menu to open the Embed Dashboard modal.
    Screen_Shot_2020-10-29_at_8.32.12_AM.png
  5. This modal displays all available public and application embeds. Click to open the Application embed tab.
    Screen_Shot_2020-08-11_at_8.14.33_PM.png

  6. Under Generate Public URL for select ‘Entire Dashboard’ or the single visualization you would like to create an embed for.
    Screen_Shot_2020-08-11_at_8.14.43_PM.png
  7. The embed path will automatically be generated. Copy this URL for future use.
    Screen_Shot_2020-08-11_at_8.16.53_PM.png

 

Adding the Embed to your Application

Creating the Embed API

Once you have your organization’s embed secret, you will need to add a server-side API to your application for the purpose of generating a secure Embed URL.

The generated URL will have the following structure:

<dashboard_embed_path>?:nonce=<random_nonce_value>&:allow_export=<allow_export_boolean>&:time=<unix_timestamp>&:session_length=<session_length>&<control_id>=<control_value>&:external_user_id=<external_user_id>&:signature=<hmac_signature>
  • <dashboard_embed_path> is the Embed Path that is generated on the dashboard you wish to embed.
  • <random_nonce_value> a random unique string (less than 255 characters). Sigma uses this to prevent application embed URLs from being shared and reused.
  • <allow_export_boolean> [optional] is a boolean (true/false) parameter that controls whether the viewer of the dashboard will be able to download data from the dashboard visualizations. If this parameter is not specified, the url will default to false and viewers will not be able to download data.
  • <unix_timestamp> is the current time as a UNIX timestamp. Sigma uses this in combination with the <session_length> to determine if your link has expired. The URL is valid after the <unix_timestamp> and before the <session_length> expiration.
  • <session_length> is the number of seconds after the Application Embed URL was generated that it should remain valid. After the specified number of seconds, the Application Embed will no longer display new values.
  • <control_id> and <control_value> are the id and value of a dashboard control you'd wish to pass through to the dashboard. You may pass multiple control ids and values. This will allow you to customize what your viewers see. Learn more.
    Note: All controls must exist on the dashboard. This is to ensure changes to a dashboard do not cause data to be visible unintentionally.
  • <external_user_id>  is a unique identifier for each individual user viewing the embed in your application. Sigma uses this identifier for licensing purposes.
  • <hmac_signature> is the url generated so far that is HMAC signed with the Sigma Embed Secret.

See Node.js Example

Fetching and Rendering the Embed URL

Once the API has been added to your application, you will need to call it from the client. The client will pass the dashboard’s embed path to the API, and the server will respond with the secure embed URL. The client can then render this embed URL in an iframe. See Node.js Example

Node.JS Example 

Server-side API Definition:

const crypto = require('crypto');
const uuid = require('uuid');

// :nonce - Any random string you like but cannot be repeated within the hour.
let searchParams = `?:nonce=${uuid.v4()}`;

// :allow_export - true to allow export/download on visualizations
searchParams += '&:allow_export=true';

// :session_length - The number of seconds the user should be allowed to view the embed
searchParams += '&:session_length=3600';

// :time - Current Time as UNIX Timestamp
searchParams += `&:time=${Math.floor(new Date().getTime() / 1000)}`;

// :external_user_id - a unique JSON string identifying the viewer
searchParams += `&:external_user_id=${user_id}`;

// `Control Id` is the Control Id from your dashboard and `controlValue` is the value you wish to pass
searchParams += `&${encodeURIComponent('Control Id')}=${encodeURIComponent(controlValue)}`;

// EMBED_PATH - Generated on your dashboard
const URL_WITH_SEARCH_PARAMS = process.env.EMBED_PATH + searchParams;

// EMBED_SECRET - Sigma Embed Secret generated in your admin portal
const SIGNATURE = crypto
    .createHmac('sha256', Buffer.from(process.env.EMBED_SECRET, 'utf8'))
    .update(Buffer.from(URL_WITH_SEARCH_PARAMS, 'utf8'))
    .digest('hex');

const URL_TO_SEND = `${URL_WITH_SEARCH_PARAMS}&:signature=${SIGNATURE}`

res.status(200).send(URL_TO_SEND);

 

Client-side Iframe Creation:

// YOUR_API_URL will be the url the API defined in the server-side code 

const resp = await fetch(YOUR_API_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': token,
  },
  body: {}
});

const embedUrl = resp.data;
<iframe
  title="your-signed-embed"
  style={{
    display: "block",
    height: "100%",
    width: "100%"
  }}
  frameBorder="0"
  src={embedUrl}
/>

 

Dashboard Controls in Embeds

If your dashboard takes advantage of dashboard controls, you may want to consider how they can impact your embedded analytics.

Hidden Controls

Dashboard authors have the option to select whether a control is accessible by dashboard viewers. If a control is visible, it can be passed values by any dashboard viewer. This includes viewers of an embedded version of the dashboard.

If a control is hidden, an embedded dashboard’s viewers will not see the control or its value(s). The only way they will be able to manipulate a hidden control’s input is through associated interactive charts or coordinated drilldowns.

Learn more about control placement.

Controls in a Dashboard URL

Dashboard authors also have the option to select whether a control can receive viewer input via the dashboard URL. Like hidden controls, this option is selectable under control placement.

When you create an embed, you may choose to include control values in the embed URL yourself. For application embedding, initial control values should be injected into the url during the server-side url generation process using <control_id> and <control_value>. Learn about controls in the URL.

It is also possible to manipulate control values through client-side Javascript events after the embed URL has been generated.

Javascript Events

After the embed URL is generated,  your application’s client can interact with its iframe through javascript actions and events. Events will allow the client to listen for variable updates that it can then use to take actions, such as passing control values to different embeds or from one of your application’s widgets to an embed.

Accessing Events in JavaScript

Example of listening for Javascript Events from Sigma:

window.addEventListener('message', function (event) {
if (
event.source === document.getElementById('sigma-iframe').contentWindow &&
event.origin === "https://app.sigmacomputing.com"
) {
console.log(event.data);
}
});

Events

Currently Sigma has two types of events:

dashboard:loaded

This event is created when a dashboard has finished loading the metadata but has not started evaluating the dashboard tiles.

{
type: 'dashboard:loaded',
dashboard: { variables: encodedVariables },
}

dashboard:variables:onchange

This event is triggered whenever a control/variable has been updated within Sigma’s iFrame through User interaction.

{
type: 'dashboard:variables:onchange',
dashboard: {
variables: {'Variable1': 'value1', 'Variable 2': 'value2' }
},
}

Attribute

 

Format

 

Description

 
dashboard.variables Object

The variables applied to the dashboard with the format

{ ‘Variable Name’: ‘value1’, ‘Variable Name2’: ‘value2’ }

Note that the values are URL encoded. Please see https://help.sigmacomputing.com/hc/en-us/articles/360045978434-Dashboard-Controls-in-the-URL for examples on how the values are encoded for the URL.

 

Updating Controls within Sigma

You can update controls within an iFrame by posting a message to the iFrame contentWindow.

const sigma_iframe = document.getElementById('sigma-iframe');
sigma_iframe.contentWindow.postMessage(
{
type: 'dashboard:variables:update',
variables: { 'Variable1': 'value1', 'Variable 2': 'value2' },
},
'https://app.sigmacomputing.com',
);

Actions

dashboard:variables:update

This action updates the current control values within the iframe’s dashboard. For this action to run, you must also select ‘Editable via URL for Viewer’ on your hidden control(s).

{
type: 'dashboard:variables:update',
variables: { 'Variable1': 'value1', 'Variable 2': 'value2' },
}

 

Related Resources 

Dashboard Embedding: An Overview
Public Embedding
Private Embedding
Dashboard Controls in the URL

 

IMPORTANT: This document is specific to Sigma dashboards. To learn about this topic for Sigma’s new Workbooks feature, please visit Application Embedding (Workbooks).