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.13/dist/quicksight-embedding-js-sdk.min.js"></script>
OR
- 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,
width: "1000px",
locale: "en-US",
footerPaddingEnabled: true,
sheetId: 'YOUR_SHEETID'
sheetTabsDisabled: false,
printEnabled: false,
defaultEmbeddingVisualType: TABLE
};
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
});
});
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
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:
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:
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:
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:
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:
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.13/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.13/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",
container: containerDiv,
parameters: {
country: "United States"
},
scrolling: "no",
height: "700px",
width: "1000px",
locale: "en-US",
footerPaddingEnabled: true,
defaultEmbeddingVisualType: "TABLE",
};
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
Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
SPDX-License-Identifier: Apache-2.0
💭 Give us feedback on your QuickSight embedding experience!