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.15/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",
        iframeResizeOnSheetChange: false, // use this option in combination with height: AutoFit, to allow iframe height to resize dynamically, based on sheet height, on changing sheets.
        width: "1000px",
        locale: "en-US",
        footerPaddingEnabled: true,
        sheetId: 'YOUR_SHEETID' // use this option to specify initial sheet id to load for the embedded dashboard
        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
    });
});

IframeResizeOnSheetChange element (optional)

You can use iframeResizeOnSheetChange option in combination with height: "AutoFit" option, when you want the embedded dashboard height to auto resize based on sheet height, on every sheet change event. The default value is false.

SheetId element (optional)

You can use the sheetId option, when you want to specify the initial sheet of the dashboard, instead of loading the first sheet of the embedded dashboard. You can provide the target sheet id of the dashboard as the value. In case the sheet id value is invalid, the first sheet of the dashboard will be loaded.

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),
da-DK (Dansk)
de-DE (Deutsch),
ja-JP (日本語),
es-ES (Español),
fr-FR (Français),
it-IT (Italiano),
nl-NL (Nederlands),
nb-NO (Norsk),
pt-BR (Português),
fi-FI (Suomi),
sv-SE (Svenska),
ko-KR (한국어),
zh-CN (中文 (简体)),
zh-TW (中文 (繁體))

Note: The above list might be out of date, as we continue adding more locales to QuickSight. For a more updated list of locales, please refer to https://docs.aws.amazon.com/quicksight/latest/user/choosing-a-language-in-quicksight.html. Any unsupported locale value will fallback to using en-US.

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.

Step 13: Initiate print from JS SDK method

This is currently only supported for dashboard embedding.

This feature allows you to initiate dashboard print, from parent website, without a navbar print icon, in the dashboard. To initiate a dashboard print from parent website, use dashboard.initiatePrint(), for example:

    dashboard.initiatePrint();

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.15/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.15/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>

License

💭 Give us feedback on your QuickSight embedding experience!

Keywords

FAQs

What is amazon-quicksight-embedding-sdk?

Is amazon-quicksight-embedding-sdk popular?

Is amazon-quicksight-embedding-sdk well maintained?

Package last updated on 07 May 2021

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

amazon-quicksight-embedding-sdk