amazon-quicksight-embedding-sdk
Advanced tools
Thank you for using the Amazon QuickSight JavaScript SDK. You can use this SDK to embed Amazon QuickSight in your HTML.
Amazon QuickSight offers three different embedded experiences with options for branding, user isolation with namespaces, and custom UI permissions:
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
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:
To get started with an embedded Q search bar, you need to create topics and also make sure that the users have the necessary permissions. For more information, see Embedding Amazon QuickSight Q Search Bar in the Amazon QuickSight User Guide. After Q is ready, follow the procedure to embed your Amazon QuickSight Q search bar in this example:
The process to set up QuickSight embedding is similar in both cases. The differences between setting up the two embedded experiences are as follows:
embedDashboard to embed a dashboard, embedQSearchBar to embed the Q search bar, and you use embedSession to embed an authoring portal.Details for each option are provided below in step 2
Do ONE of the following:
<script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.18.0/dist/quicksight-embedding-js-sdk.min.js"></script>
OR
npm install amazon-quicksight-embedding-sdk
var QuickSightEmbedding = require("amazon-quicksight-embedding-sdk");
You can also use ES6 import syntax in place of require:
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);
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);
You can also use ES6 import syntax in place of require:
import { embedQSearchBar } from 'amazon-quicksight-embedding-sdk';
const session = embedQSearchBar(options);
Alternatively, if you need to load the entire module:
import * as QuickSightEmbedding from 'amazon-quicksight-embedding-sdk';
const session = QuickSightEmbedding.embedQSearchBar(options);
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
undoRedoDisabled: false, // set this option to true to disable undo and redo buttons for dashboard embedding
resetDisabled: false, // set this option to true to disable reset button for dashboard embedding
defaultEmbeddingVisualType: TABLE // this option only applies to experience embedding and will not be used for dashboard embedding
};
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.
The container element is the parent HTMLElement where we're going to embed QuickSight. You can make it one of the following:
container: document.getElementById("embeddingContainer")
container: "#embeddingContainer"
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
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.
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
});
});
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.
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.
You can customize style of the iFrame that holds your dashboard by one of the followings:
quicksight-embedding-iframe {
margin: 5px;
}
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.
Note for Q search bar embedding, you'll likely want to use this to give the iframe a position: absolute so that when expanded it does not shift the contents of your application. If elements in your application are appearing in front of the Q search bar, you can provide the iframe with a higher z-index as well.
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.
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.
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.
The undoRedoDisabled element can be used to disable undo and redo buttons for dashboard embedding. If this option is set to true, the undo redo buttons will not be shown. The default value is false.
The resetDisabled element can be used to disable reset button for dashboard embedding. If this option is set to true, the reset button will not be shown. The default value is false.
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.
The qSearchBarOptions object is to specify Q specific options when embedding:
var qSearchBarOptions = {
expandCallback: () => {},
collapseCallback: () => {},
iconDisabled: false,
topicNameDisabled: false,
themeId: 'theme12345',
allowTopicSelection: true
};
The expandCallback in qSearchBarOptions can be used to specify behavior for your application when the Q search bar is expanded (clicked into).
The collapseCallback in qSearchBarOptions can be used to specify behavior for your application when the Q search bar is collapsed (clicked out of).
The iconDisabled element in qSearchBarOptions can be used to customize whether or not the QuickSight Q icon appears in the embedded search bar. The default value is false.
The topicNameDisabled element in qSearchBarOptions can be used to customize whether or not the QuickSight Q Topic name appears in the embedded search bar. The default value is false.
The themeId element in qSearchBarOptions can be used to set a content theme for the embedded search bar. Note that the embedded QuickSight user, or the group or namespace they belong to, must have permissions on this theme. The default theme is the default QuickSight theme seen in the console application.
The allowTopicSelection element in qSearchBarOptions can be used to customize whether or not the embedded user can change the selected topic for the Q search bar. Note that this can only be set to false if the initialTopicId was specified in the embedding API; for more information, see QuickSight Embedding APIs. The default value is true.
var dashboard = QuickSightEmbedding.embedDashboard(options);
This returns a dashboard object for further action.
var session = QuickSightEmbedding.embedSession(options);
This returns an console session object for further action.
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,
dashboard.on("load", yourLoadCallback);
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,
dashboard.on("error", yourErrorCallback);
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.
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.
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]" });
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]" });
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.
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);
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,
dashboard.on("parametersChange", yourParametersChangeCallback);
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,
dashboard.on("selectedSheetChange", yourSelectedSheetChangeCallback);
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.
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.
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();
expandCallback and collapseCallback to create a backdrop/element on the page that's always clickable so that the document listener can properly close the search bar. <!DOCTYPE html>
<html>
<head>
<title>Basic Embed</title>
<script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.18.0/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>
<!DOCTYPE html>
<html>
<head>
<title>QuickSight Console Embedding</title>
<script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.18.0/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>
<!DOCTYPE html>
<html>
<head>
<title>QuickSight Q Search Bar Embedding</title>
<script src="https://unpkg.com/amazon-quicksight-embedding-sdk@1.18.0/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 onExpand() {
console.log("Do something when the Q search bar opens");
}
function onCollapse() {
console.log("Do something when the Q search bar closes");
}
function embedQSearchBar() {
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,
width: "1000px",
locale: "en-US",
qSearchBarOptions: {
expandCallback: onExpand,
collapseCallback: onCollapse,
iconDisabled: false,
topicNameDisabled: false,
themeId: 'theme12345',
allowTopicSelection: true
}
};
session = QuickSightEmbedding.embedQSearchBar(options);
session.on("error", onError);
}
function onCountryChange(obj) {
session.setParameters({country: obj.value});
}
</script>
</head>
<body onload="embedQSearchBar()">
<div id="embeddingContainer"></div>
</body>
</html>
Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0
FAQs
JS SDK for embedding Amazon QuickSight
The npm package amazon-quicksight-embedding-sdk receives a total of 56,386 weekly downloads. As such, amazon-quicksight-embedding-sdk popularity was classified as popular.
We found that amazon-quicksight-embedding-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
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.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.