Embed Visualizations Using Iframes

An iframe is used to display a web content from one website inside another website. You can use iframes to embed your dashboards and Analytical Designer inside your web applications.

Embed Dashboards

Generate an iframe code snippet that contains your dashboard for use in your web applications.

Steps:

  1. Open the dashboard you want to embed.

  2. Click the </> button in the top right corner.

    Embedding button

    The embedding dialog opens.

  3. Select Iframe.

    Embedding dialog for iframes
  4. Configure the embedding options as needed. See the Configuration Options section.

  5. Click Copy code to copy the iframe code snippet to your clipboard.

    You can now use the code snippet to embed the dashboard into your web application.

    Dashboard embeded with iframe

Configuration Options

The following configurations options are available to you when embedding visualizations with iframes:

  • If you do not want the navigation panel listing dashboards to be visible, add the ?showNavigation=false parameter to the URL:
  • To hide the Embed button, add the ?showEmbedButton=false parameter to the URL:
  • To hide the filter bar, add the ?hideControl=[filterBar] parameter to the URL:
  • To hide the list of visualizations and other items that you can add to dashboards, add the ?hideControl=[widgetsCatalogue] parameter to the URL:
  • To hide the top bar, add the ?hideControl=[topBar] parameter to the URL:
  • To hide the Save as new or Delete buttons, add the ?hideControl=[deleteButton,saveAsButton] parameter to the URL:

For example to embed a dashboard without the navigation panel and embed button, you would use the following url:

<host_url>/dashboards/embedded/#/workspace/<workspace_id>/dashboard/<dashboard_id>?showNavigation=false?showEmbedButton=false

PostMessages

Dashboards embeded in iframes supports communication via postMessages. See Communication with Embedded Dashboards Using PostMessages.

Limitations

Please take the following limitations into account when embedding a dashboard into your web app:

  • Iframe width:

    If you use less than 1170 px of horizontal space for the embedded component, the Edit button and all controls for saving in edit mode are not displayed.

  • Iframe height:

    Ensure the iframe height is no larger than the browser window height. This prevents modal dialogs from stretching incorrectly. For proper display and functionality, set the iframe height to be equal to or less than the browser window height.

Embed the Analytical Designer

Embed the analytical designed using an iframe for use in your web applications.

Steps:

  1. Click the Analyze tab.

  2. Check the URL in the browser address bar. For example:

    <host_url>/analyze/#/<workspace_id>/reportId/edit
    
  3. Add the string /embedded/ into the URL after /analyze:

    <host_url>/analyze/embedded/#/<workspace_id>/reportId/edit
    
  4. Embed the link into your application using an Iframe:

    <iframe src="<host_url>/analyze/embedded/#/<workspace_id>/reportId/edit" frameborder="0"></iframe>
    

Customize the URL To Open a Specific Visualization

If you want the embedded Analytical Designer to open a specific visualization, replace the reportId section in the embed URL with the ID of the visualization that you want to open.

The URL for embedding would then look like:

<host_url>/analyze/embedded/#/<workspace_id>/<insight_id>/edit

Limitations

Please take the following limitations into account when embedding a dashboard into your web app:

  • Iframe width:

    The minimum dimension of 1100x575 pixels is required for Analytical Designer to be embedded correctly.

  • Iframe height:

    Ensure the iframe height is no larger than the browser window height. This prevents modal dialogs from stretching incorrectly. For proper display and functionality, set the iframe height to be equal to or less than the browser window height.

Authenticate With Injected API Token

If you are using an OpenID Connect (OIDC) identity provider for authentication, the authentication process should be automatic. However, if you want to use API tokens for authentication, you will need to handle this type of authentication manually.

To set up authentication using API token for an embedded dashboard or Analytical Designer:

  1. Embed the dashboard or Analytical Designer application using the iframe.

  2. Add apiTokenAuthentication=true query parameter to the URL.

  3. Implement a message listener in the embedding page to listen to events sent by the dashboards or Analytical Designer. The listener must wait for a listeningForApiToken event.

    When the event is received, the dashboard or Analytical Designer is ready to receive the API token value.

  4. Send a postMessage command to the iframe with the API token value.

    The dashboard or Analytical Designer will continue with initialization and use the token for authentication of all API calls from now on.

See the Example below for implementation details.

Example

You may reuse the following code snippet. Do not forget to replace <host_url>, <workspace_id>, <insight_id>, <dashboard_id>, and <api_token_value> with your own values.

For Analytical Designer, use:

  • analyticalDesigner as <application_identifier>
  • <host_url>/analyze/embedded/#/<workspace_id>/<insight_id>/edit?apiTokenAuthentication=true as <embedding_URL>

For Dashboards, use:

  • dashboard as <application_identifier>
  • <host_url>/dashboards/embedded/#/workspace/<workspace_id>/dashboard/<dashboard_id>?apiTokenAuthentication=true as <embedding_URL>
<iframe
    title="Embed GD Application"
    id="embedded-app-frame"
    src="<embedding_URL>"
    width="1300"
    height="800"
></iframe>
<script>
    console.log("Setup parent frame message listener")

    window.addEventListener(
        "message",
        function (event) {
            console.log("Post message received", event);

            if (event.data.gdc?.event.name === "listeningForApiToken") {
                const postMessageStructure = {
                    gdc: {
                        product: "<application_identifier>",
                        event: {
                            name: "setApiToken",
                            data: {
                                token: "<api_token_value>"
                            }
                        }
                    }
                };
                console.log("Sending token to embedded window");

                const origin = "*";
                const iframe = document.getElementById("embedded-app-frame").contentWindow;
                iframe.postMessage(postMessageStructure, origin);
            }
        },
        false
    );
</script>

Using JWT

If you are using JWT instead of an API token for authentication edit your event data payload in the following way:

event: {
    name: "setApiToken",
    data: {
        token: "<jwt_token_value>",
        type: "jwt",
        secondsBeforeTokenExpirationToEmitReminder: 60
    }
}

When the token is 60 seconds from expiring, the apiTokenIsAboutToExpire event is emitted to notify you and give you a chance to post a fresh token. Note that 60 seconds is the default value, but you can change it.

We recommend you check out the Create JWK and JWT in JavaScript to get started on handling JWTs inside JavaScript.

Example Using Authentication Using Injected JWT

This is a modified example of the API token injection example shown above that has been modified to better suit the JWT use case:

<iframe
        title="Embed GD Application"
        id="embedded-app-frame"
        src="<embedding_URL>"
        width="1300"
        height="800"
></iframe>
<script>
    console.log("Setup parent frame message listener")

    window.addEventListener(
        "message",
        function (event) {
            console.log("Post message received", event);

            const eventName = event.data.gdc?.event.name;

            // Send new token when embedded application ask for it for the first time and then subsequently
            // each 60 seconds before the previous token expires. 
            if (eventName === "listeningForApiToken" || eventName === "apiTokenIsAboutToExpire") {
                // Fetch token from JWT generator endpoint, for example Node.JS Express application.
                // The application must ensure that the call is authenticated, for example via request cookie
                // or through SSO
                fetch(`/api/jwt-generator?user=john.doe`, {
                    method: "GET"
                }).then(function (response) {
                    if (response.ok) {
                        return response.json();
                    }
                    throw response;
                }).then(function (data) {
                    const postMessageStructure = {
                        gdc: {
                            product: "<application_identifier>",
                            event: {
                                name: "setApiToken",
                                data: {
                                    token: data.jwt, // example expects the response is {"jwt": "<jwt_value>"}
                                    type: "jwt",
                                    secondsBeforeTokenExpirationToEmitReminder: 60,
                                }
                            }
                        }
                    };

                    console.log("Sending JWT to embedded window");

                    const origin = "*";
                    const iframe = document.getElementById("embedded-app-frame").contentWindow;
                    iframe.postMessage(postMessageStructure, origin);
                });
            }
        },
        false
    );
</script>