Amazon QuickSight Embedding SDK

Thank you for using the Amazon QuickSight JavaScript SDK. You can use this SDK to embed Amazon QuickSight in your HTML.

Usage

Amazon QuickSight offers two different embedded experiences with options for branding, user isolation with namespaces, and custom UI permissions:

Embedded authoring portals provide the QuickSight authoring experience

To get started with an embedded authoring portal, you need to make sure that the users are granted the necessary permissions. For more information, see Embedding the Amazon QuickSight Console

Embedded dashboards provide an interactive read-only experience

To get started with an embedded dashboard, you need to publish it and also make sure that the users have the necessary permissions. For more information, see Embedding Amazon QuickSight Dashboards in the Amazon QuickSight User Guide. After a dashboard is ready, follow the procedure to embed your Amazon QuickSight dashboard in this example:

Setup differences between embedded QuickSight experiences: dashboards and portals

The process to set up QuickSight embedding is similar in both cases. The differences between setting up the two embedded experiences are as follows:

You use a different SDK object for each embedded QuickSight experience. You use embedDashboard to embed a dashboard, and you use embedSession to embed an authoring portal.
You use a different API for each embedded experience. For more information, see QuickSight Embedding APIs
Different options are supported for each embedded experience.

Embedded dashboards are always read-only. The level of interactivity is set when the dashboard is published.
Embedded authoring ports allow the user to create QuickSight assets, just like they can in the AWS console for QuickSight. Exactly what the user can do in the console is controlled by a custom permission profile. The profile can remove abilities such as creating or updating data sources and datasets. You can set also the default visual type. Embedded consoles currently don't support screen scaling in formatting options.

Details for each option are provided below in step 2

Step 1: Download and include QuickSight Embedding SDK

Do ONE of the following:

Option 1: Use the Amazon QuickSight Embedding SDK in the browser:

    <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.0.12/dist/quicksight-embedding-js-sdk.min.js"></script>

Option 2: Install and use the QuickSight Embedding SDK in Node.js:

    npm install amazon-quicksight-embedding-sdk

    var QuickSightEmbedding = require("amazon-quicksight-embedding-sdk");

You can also use ES6 import syntax in place of require:

For the embedded dashboard experience

    import { embedDashboard } from 'amazon-quicksight-embedding-sdk';

    const dashboard = embedDashboard(options);

Alternatively, if you need to load the entire module:

    import * as QuickSightEmbedding from 'amazon-quicksight-embedding-sdk';

    const dashboard = QuickSightEmbedding.embedDashboard(options);

For the embedded console experience (authoring portals)

You can also use ES6 import syntax in place of require:

    import { embedSession } from 'amazon-quicksight-embedding-sdk';

    const session = embedSession(options);

Alternatively, if you need to load the entire module:

    import * as QuickSightEmbedding from 'amazon-quicksight-embedding-sdk';

    const session = QuickSightEmbedding.embedSession(options);

Step 2: Configure embedding

Set up the embedded QuickSight console options.

    var options = {
        url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",
        container: document.getElementById("embeddingContainer"),
        parameters: {
            country: "United States",
            states: [
                "California",
                "Washington"
            ]
        },
        scrolling: "no",
        height: "700px",
        width: "1000px",
        locale: "en-US",
        footerPaddingEnabled: true,
        sheetTabsDisabled: false, // use this option to enable or disable sheet tab controls in dashboard embedding
        printEnabled: false, // use this option to enable or disable print option for dashboard embedding
        defaultEmbeddingVisualType: TABLE // this option only applies to experience embedding and will not be used for dashboard embedding
    };

URL element (required)

If you haven't done it yet, to generate the embedding URL for dashboard embedding, follow Embedding Amazon QuickSight Dashboards in the Amazon QuickSight User Guide to generate the url.

To generate the embedding URL for console embedding, follow Embedding the Amazon QuickSight Console in the Amazon QuickSight User Guide to generate the URL.

Container element (required)

The container element is the parent HTMLElement where we're going to embed QuickSight. You can make it one of the following:

Option 1: It can be an HTMLElement:

    container: document.getElementById("embeddingContainer")

Option 2: Or, it can be a query selector string:

    container: "#embeddingContainer"

Parameters element (optional)

The parameters element is an object that contains key:value pairs for parameters names:values. It allows you to set initial parameter values for your embedded QuickSight session. Pass an array as value for multi-value parameters. For more information about parameters in Amazon QuickSight, see https://docs.aws.amazon.com/quicksight/latest/user/parameters-in-quicksight.html

Scrolling element (optional)

The scrolling element lets you set up a specific scrolling experience for the iFrame that holds your embedded QuickSight session. Available values are auto, yes, and no. The default value is no.

Width element and height element (optional)

You can set width and height for the iFrame that holds your embedded QuickSight session. Both of these default to 100%. You can set them to be fixed values:

    height: "700px",
    width: "1000px"

Or, relative values:

    height: "80%",
    width: "60%"

To make your embedded QuickSight session responsive, don't set width or height (leave them at the default: 100%). Then you can make the container HTMLElement responsive to screen size change.

You can also choose to set height to be AutoFit to make the iFrame fit your dashboard height. Use loadingHeight to specify the height you'd like to use before actual dashboard height is known. This is currently only supported for dashboard embedding:

    height: "AutoFit",
    loadingHeight: "700px"

Note: With AutoFit height enabled, modals generated by the dashboard can be hidden if the content is larger than the screen. An example of this type of modal is the one that displays when you select "Export to CSV" on a Table visual. To solve this issue, you can add the following code to autoscroll the focus to the modal.

dashboard.on("SHOW_MODAL_EVENT", () => {
    window.scrollTo({
        top: 0 // iFrame top position
    });
});

ClassName element (optional)

You can customize style of the iFrame that holds your dashboard by one of the followings:

Option 1: Use the "quicksight-embedding-iframe" class we predefined for you:

quicksight-embedding-iframe {
    margin: 5px;
}

Option 2: Or, create your own class and pass in through className element:

your-own-class {
    margin: 5px;
}

    className: "your-own-class",

We've overridden the border and padding of the iFrame to be 0px, because setting border and padding on the iFrame might cause unexpected issues. If you have to set border and padding on the embedded QuickSight session, set it on the container div that contains the iFrame.

Locale element (optional)

You can set locale for the embedded QuickSight session:

    locale: "en-US",

Available locale options are:

en-US (English),
de-DE (Deutsch),
ja-JP (日本語),
es-ES (Español),
fr-FR (Français),
it-IT (Italiano),
pt-BR (Português),
ko-KR (한국어),
zh-CN (中文 (简体)),
zh-TW (中文 (繁體))

DefaultEmbeddingVisualType for QuickSight console embedding (optional)

You can set the embedding visual type for embedded sessions. The default visual type provided in the options will be used during visual creating. By default, when you add a new visual in an embedded session, AutoGraph is selected by default. This setting can be overridden to Table by setting the following option:

    defaultEmbeddingVisualType: "TABLE"

Available options for default visual types in embedding are:

AUTO_GRAPH,
TABLE

FooterPaddingEnabled element (optional)

The footerPaddingEnabled element adds 22 pixels of space at the bottom of the layout. For example, you can set this to true if the "Powered by QuickSight" footer blocks part of your visual. The default value is false.

PrintEnabled element (optional)

The printEnabled element can be used to enable or disable print option for dashboard embedding. The default value is false. And, if both undoRedo and reset options are disabled, the navbar and print option wont be shown anyways, even if printEnabled is true.

SheetTabsDisabled element (optional)

This is currently only supported for dashboard embedding. The sheetTabsDisabled element can be used to enable or disable sheet tab controls in dashboard embedding. The default value is false.

Step 3: Create the QuickSight session object

Dashboard embedding

    var dashboard = QuickSightEmbedding.embedDashboard(options);

This returns a dashboard object for further action.

Console embedding

    var session = QuickSightEmbedding.embedSession(options);

This returns an console session object for further action.

Step 4: Setup load callback (optional)

This is currently only supported for dashboard embedding.

If you want your application to get notified and respond when the Amazon QuickSight dashboard is fully loaded, use a load callback. Choose one of the following:

Use options:

    loadCallback: yourLoadCallback,

Or, register the "load" event on the returned dashboard object:

    dashboard.on("load", yourLoadCallback);

Step 5: Setup error callback (optional)

If you want your application get notified and respond when the embedded QuickSight session fails to load, use a error callback. Choose one of the following:

Use options:

    errorCallback: yourErrorCallback,

Or, register the "error" event on the returned dashboard object:

     dashboard.on("error", yourErrorCallback);

To register the "error" event on the returned console session object:

     session.on("error", yourErrorCallback);

We pass a payload object to your callback function with a specific payload.errorCode. Currently, the error codes are:

Forbidden -- the URL's authentication code expired
Unauthorized -- the session obtained from the authentication code expired

If you follow the instructions to generate the correct URL, but you still receive these error codes, you need to generate a new URL.

Step 6: Update parameter values (optional)

Use setParameters() to update parameter values. Pass an array as value for multi-value parameters. You can build your own UI to trigger this, so that viewers of the embedded QuickSight session can control it from your app page.

Dashboard embedding

Parameters in an embedded dashboard session can be set by using the following call:

    dashboard.setParameters({country: "United States", states: ["California", "Washington"]});

To reset a parameter so that it includes all values, you can pass the string "[ALL]".

    dashboard.setParameters({country: "United States", states: "[ALL]" });

Console embedding

Parameters in an embedded console session can be set by using the following call:

    session.setParameters({country: "United States", states: ["California", "Washington"]});

To reset a parameter so that it includes all values, you can pass the string "[ALL]".

    session.setParameters({country: "United States", states: "[ALL]" });

Step 7: Navigate to different dashboard (optional)

Dashboard embedding

To navigate to a different dashboard, use dashboard.navigateToDashboard(options). The input parameter options should contain the dashboardId that you want to navigate to, and also the parameters for that dashboard, for example:

    var options = {
        dashboardId: "37a99f75-8230-4409-ac52-e45c652cc21e",
        parameters: {
            country: [
                "United States"
            ]
        }
    };
    dashboard.navigateToDashboard(options);

This function is only supported for embedded dashboards.

Step 8: Navigate to sheet (optional)

This is currently only supported for dashboard embedding.

If you want to navigate from one sheet to another programmatically, with the Amazon quicksight dashboard, use the below method:

    dashboard.navigateToSheet(sheetId);

Step 9: Setup parameters change callback (optional)

This is currently only supported for dashboard embedding.

If you want your application to get notified and respond when the parameters in Amazon QuickSight dashboard changes, use the parameter change callback. Choose one of the following:

Use options:

    parametersChangeCallback: yourParametersChangeCallback,

Or, register the "parametersChange" event on the returned dashboard object:

    dashboard.on("parametersChange", yourParametersChangeCallback);

Step 10: Setup selected sheet change callback (optional)

This is currently only supported for dashboard embedding.

If you want your application to get notified and respond when the selected sheet in Amazon QuickSight dashboard changes, use the selected sheet change callback. Choose one of the following:

Use options:

    selectedSheetChangeCallback: yourSelectedSheetChangeCallback,

Or, register the "selectedSheetChange" event on the returned dashboard object:

    dashboard.on("selectedSheetChange", yourSelectedSheetChangeCallback);

Step 11: Get active parameter values (optional)

This is currently only supported for dashboard embedding.

If you want to get the active parameter values, from Amazon Quicksight dashboard in ad-hoc manner, use the below method with a callback:

    dashboard.getActiveParameterValues(yourCallback);

The callback is needed since the process of getting active parameter values is asynchronous, even for ad-hoc fetches.

Step 12: Get sheets (optional)

This is currently only supported for dashboard embedding.

If you want to get the current set of sheets, from Amazon Quicksight dashboard in ad-hoc manner, use the below method with a callback:

    dashboard.getSheets(yourCallback);

The callback is needed since the process of getting sheets is asynchronous, even for ad-hoc fetches.

Troubleshooting

Make sure the URL you provide in options is not encoded. You should avoid using an encoded URL because it breaks the authcode in the URL by changing it. Also, check that the URL sent in the response from the server side is not encoded.
The URL only works if it used with the authcode it came with. The URL and authcode need to be used together. They expire after five minutes, so it's worth checking that you're not troubleshooting an expired combination of URL and authcode.
Some browsers (e.g. mobile safari) have default setting to "Always Block Cookies". Change the setting to either "Allow form Websites I Visit" or "Always Allow".

Example

Dashboard embedding

    <!DOCTYPE html>
    <html>

    <head>
        <title>Basic Embed</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.0.12/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            var dashboard
            function onDashboardLoad(payload) {
                console.log("Do something when the dashboard is fully loaded.");
            }

            function onError(payload) {
                console.log("Do something when the dashboard fails loading");
            }

            function embedDashboard() {
                var containerDiv = document.getElementById("embeddingContainer");
                var options = {
                    url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode",
                    container: containerDiv,
                    parameters: {
                        country: "United States"
                    },
                    scrolling: "no",
                    height: "700px",
                    width: "1000px",
                    locale: "en-US",
                    footerPaddingEnabled: true
                };
                dashboard = QuickSightEmbedding.embedDashboard(options);
                dashboard.on("error", onError);
                dashboard.on("load", onDashboardLoad);
            }

            function onCountryChange(obj) {
                dashboard.setParameters({country: obj.value});
            }
        </script>
    </head>

    <body onload="embedDashboard()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country" onchange="onCountryChange(this)">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="embeddingContainer"></div>
    </body>

    </html>

QuickSight console embedding

    <!DOCTYPE html>
    <html>

    <head>
        <title>QuickSight Console Embedding</title>
        <script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.0.12/dist/quicksight-embedding-js-sdk.min.js"></script>
        <script type="text/javascript">
            var session

            function onError(payload) {
                console.log("Do something when the session fails loading");
            }

            function embedSession() {
                var containerDiv = document.getElementById("embeddingContainer");
                var options = {
                    url: "https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/dashboardId?isauthcode=true&identityprovider=quicksight&code=authcode", // replace this dummy url with the one generated via embedding API
                    container: containerDiv,
                    parameters: {
                        country: "United States"
                    },
                    scrolling: "no",
                    height: "700px",
                    width: "1000px",
                    locale: "en-US",
                    footerPaddingEnabled: true,
                    defaultEmbeddingVisualType: "TABLE", // this option only applies to QuickSight console embedding and is not used for dashboard embedding
                };
                session = QuickSightEmbedding.embedSession(options);
                session.on("error", onError);
            }

            function onCountryChange(obj) {
                session.setParameters({country: obj.value});
            }
        </script>
    </head>

    <body onload="embedSession()">
        <span>
            <label for="country">Country</label>
            <select id="country" name="country" onchange="onCountryChange(this)">
                <option value="United States">United States</option>
                <option value="Mexico">Mexico</option>
                <option value="Canada">Canada</option>
            </select>
        </span>
        <div id="embeddingContainer"></div>
    </body>

    </html>

Change Log

1.0.12

navigateToDashboard function for switching to another authorized dashboard without submitting a new URL
navigateToSheet function for switching to another sheet on an already embedded dashboard
parametersChangeCallback option to receive a callback when changing parameters in dashboard
selectedSheetChangeCallback option to receive a callback when sheet is successfully changed on the embedded dashboard
getSheets function to get list of sheets on currently rendered dashboard in ad-hoc manner
getActiveParameterValues function to get currently applied parameters in ad-hoc manner
printEnabled option to add a Print button for embedded dashboard
sheetTabsDisabled option to disable tabs display on a multi-sheet embedded dashboard

1.0.11

Fixed dashboard embedding issue in IE11
Updated elliptic to 6.5.3 to resolve security issues
Fixed serialize-javascript vulnerability

1.0.9

Added support for session embedding
Added option for default visual type for session embedding
Updated Babel to the latest version

1.0.7

Added option to enable footer padding.

1.0.6

Supported setting locale.

1.0.5

Fixed compatibility with IE 11 when updating parameter values.
Improved README.

1.0.4

Added SHOW_MODAL_EVENT to notify modal is shown in Dashboard.

1.0.3:

Added "AutoFit" as a new height option.

1.0.2:

Added support for multi-value parameters.

1.0.1:

Initial release.

sveisvei/amazon-quicksight-embedding-sdk

Amazon QuickSight Embedding SDK

Usage

Setup differences between embedded QuickSight experiences: dashboards and portals

Step 1: Download and include QuickSight Embedding SDK

For the embedded dashboard experience

For the embedded console experience (authoring portals)

Step 2: Configure embedding

URL element (required)

Container element (required)

Parameters element (optional)

Scrolling element (optional)

Width element and height element (optional)

ClassName element (optional)

Locale element (optional)

DefaultEmbeddingVisualType for QuickSight console embedding (optional)

FooterPaddingEnabled element (optional)

PrintEnabled element (optional)

SheetTabsDisabled element (optional)

Step 3: Create the QuickSight session object

Dashboard embedding

Console embedding

Step 4: Setup load callback (optional)

Step 5: Setup error callback (optional)

Step 6: Update parameter values (optional)

Dashboard embedding

Console embedding

Step 7: Navigate to different dashboard (optional)

Dashboard embedding

Step 8: Navigate to sheet (optional)

Step 9: Setup parameters change callback (optional)

Step 10: Setup selected sheet change callback (optional)

Step 11: Get active parameter values (optional)

Step 12: Get sheets (optional)

Troubleshooting

Example

Dashboard embedding

QuickSight console embedding

Change Log

License