Embedded Analytics: Communication Between Parent and Embed Application

Sigma provides users with powerful ways to establish a bi-directional communication channel between your application and an embedded dashboard. This allows your application to both control the embed and react changes happening within it.

How to control the embed from your application

The way your application controls the embed is through the iframe URL. The URL provides an extensive set of parameters that you can leverage to control the content of the embed. Additionally, you can add a signature to the URL, making it a securely-signed URL and preventing modification and reuse by other people.

The parameters let you manage:

• The user (Their access permission, the team they belong to, their current session)
• The workbook content (The workbook to display, the filters applied)
• The embed display option (Hiding interactions, hiding the navigation)

The parameters are passed in the URL as standard URL search parameters.

The full list of supported parameters is:

:clientId=<string>

The client Id associated with the client credentials used to generate the signature. Sigma uses this parameter to verify the signature. If not specified, Sigma assumes the signature has been generated with the default organization embed client credentials. We recommend passing an explicit clientId to make management and security easier.

:nonce=<string>

Unique value that prevents application embed URLs from being shared and reused.

:signature=<string>

Signature of the url, using the client credentials identified by the “:clientId” parameter or the org default client credentials if no “:clientId” is provided.

:time=<int>

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 <:time> and before the <:session_length> expiration.

:session_length=<int>

The number of seconds the embed URL should remain valid after the application embed URL was generated. Maximum value is 2592000 seconds (30 days.)

:allow_export=<true | false>

Controls whether the viewer of the embed will be able to export data. If not specified, default to “false”. This parameter is overridden by the account type permission if the “:account_type” parameter is specified.

<control_id>=<control_value>

Allow to specify the value of controls (filters, parameters) in your dashboard.

:mode=<view | explore | userbacked>

Allow viewers to be able to explore/manipulate the embed.

:hide_sheet_interactions=<true | false>

Remove all interactions on the embed, default to false. Useful for small embedded dashboards where the interaction options hide the data.

:hide_tooltip=<true | false>

Remove the tooltip, default to false. Useful for small embedded dashboards where the interaction options hide the data.

:hide_folder_navigation=<true | false>

Remove the navigation menu, default to false. Useful if you want to manage the navigation from your application.

‍

The following additional parameters allow you to apply access control at the user level on your embedded dashboard. Those parameters allow you to create embedded users in Sigma and configure their permission and data access. In particular, it allows you to implement Row Level Security at the user level:

:external_user_id=<string>

Id of the user in your system. Sigma has no specific expectation about the value. Used for identification and data access management.

:email=<string>

Email of the user, used for exports and identification. No checks are done on the email from sigma and we trust that the email passed in is working and belongs to the user.

:account_type=<string>

Account type to associate with the user and control the features the user has access to. Can be a custom defined account type.

:external_user_team=<string>

Team that the embedded user should be associated with. You can pass multiple teams by separating them with commas.

:ua_<user_attribute_name>=<attribute_value>

Attributes values to associate with the user. This can then be used to implement Row Level Security or dynamically change the connection parameters used for the user when connecting to the CDW.

How to react to change in the embed

Sigma provides an event API to notify your application of events happening in the context of the embedded dashboard. It is not required to use this API. However, if you do use it, it will allow you to react to events and implement specific UX behaviors, such as:

• You want to persist the state of filters for a given user so that you can bring them back to the same view in the future.
• You want to display contextual information in your application, based on what the user selects in the embedded dashboard.

How to use it

Add an event listener for the ‘message’ event type in your javascript.

For example if you want to log the received events in your debugger console, you would add this in your application javascript. If you want to experiment with it, you can also paste it in your browser debugger and see the events being sent in real time:

addEventListener('message', function(event) {
  console.debug(
    `postMessage received by from '${event.origin}' with data:`,
    event.data
  );
});

Events type currently supported

workbook:loaded

{ 
    type: 'workbook:loaded'; 
    workbook: { 
        variables: Record<string, string>;
    } 
}

'workbook:published'

{
    type: 'workbook:published';
    workbookId: string;
}

workbook:fullscreen:onchange

{
    type: 'workbook:fullscreen:onchange';
    fullScreen: boolean;
}

workbook:pageheight:onchange

{
    type: 'workbook:pageheight:onchange';
    pageHeight: number;
}

workbook:selectednodeid:onchange

{
    type: 'workbook:selectednodeid:onchange';
    selectedNodeId: string | null;
}

workbook:variables:onchange

{
    type: 'workbook:variables:onchange';
    workbook: { variables: Record<string, string> };
}

url:onchange

{
    type: 'url:onchange';
    url: string
}

workbook:table:oncellselect

{
    type: 'workbook:table:oncellselect';
    nodeId: string;
    title: string;
    cells: Array<{
        value: Object | Date | boolean | number | string | null;
        cellType: 'valueCell';
        columnName: string;
        underlyingData: {
            rows: Array<
                Record
                    >;
            isTruncated: boolean;
            length: number;
        };
    }>
;
}

workbook:pivottable:oncellselect

{
    type: 'workbook:pivottable:oncellselect';
    nodeId: string;
    title: string;
    cells: Array<{
        value: Object | Date | boolean | number | string | null;
        cellType: 'valueCell' | 'rowHeader' | 'columnHeader';
        columnName: string;
        rowPath: null | Array<{
            name: string;
            value: Value_t;
        }>;
        columnPath: null | Array<{
            name: string;
            value: Value_t;
        }>;
    }>
}

workbook:chart:onvalueselect

{
    type: 'workbook:chart:onvalueselect';
    nodeId: string;
    title: string;
    values: ChartValues_t;
}

Sigma makes your embedded experience fast, easy-to-scale, and performant. To find out more about how you can deliver a great user experience, schedule your demo today.