Important: We've redesigned the Amazon QuickSight analysis workspace. You might encounter screenshots or procedural text that doesn't reflect the new look in the QuickSight console. We're in the process of updating screenshots and procedural text.
To find a feature or item, use the Quick search bar.
For more information on QuickSight's new look, see Introducing new analysis experience on Amazon QuickSight.
Step 3: Embed the console session URL
In the following section, you can find out how you can use the Amazon QuickSight Embedding
SDK (JavaScript) to embed the console session URL from step 3 in your website or
application page. With the SDK, you can do the following:
-
Place the console session on an HTML page.
-
Pass parameters into the console session.
-
Handle error states with messages that are customized to your application.
Call the GenerateEmbedUrlForRegisteredUser API operation to generate the URL that you can embed in
your app. This URL is valid for 5 minutes, and the resulting session is valid for up to 10 hours.
The API operation provides the URL with an auth_code that enables a single-sign
on session.
The following shows an example response from generate-embed-url-for-registered-user.
//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
{
"Status": "200",
"EmbedUrl": "https://quicksightdomain/embedding/12345/start...",
"RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
}
Embed this console session in your webpage by using the QuickSight Embedding SDK or
by adding this URL into an iframe. If you set a fixed height and width number (in pixels),
QuickSight uses those and doesn't change your visual as your window resizes. If you set a
relative percent height and width, QuickSight provides a responsive layout that is modified as
your window size changes. By using the Amazon QuickSight Embedding SDK, you can also control parameters
within the console session and receive callbacks in terms of page load completion and errors.
The domain that is going to host embedded dashboards must be on the allow list, the list of approved domains for your
Amazon QuickSight subscription. This requirement protects your data by
keeping unapproved domains from hosting embedded dashboards. For more
information about adding domains for an embedded console, see Allow listing domains at runtime
with the QuickSight API.
The following example shows how to use the generated URL. This code is generated on your app
server.
- SDK 2.0
-
<!DOCTYPE html>
<html>
<head>
<title>Console Embedding Example</title>
<script src="https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js"></script>
<script type="text/javascript">
const embedSession = async() => {
const {
createEmbeddingContext,
} = QuickSightEmbedding;
const embeddingContext = await createEmbeddingContext({
onChange: (changeEvent, metadata) => {
console.log('Context received a change', changeEvent, metadata);
},
});
const frameOptions = {
url: "<YOUR_EMBED_URL>", // replace this value with the url generated via embedding API
container: '#experience-container',
height: "700px",
width: "1000px",
onChange: (changeEvent, metadata) => {
switch (changeEvent.eventName) {
case 'FRAME_MOUNTED': {
console.log("Do something when the experience frame is mounted.");
break;
}
case 'FRAME_LOADED': {
console.log("Do something when the experience frame is loaded.");
break;
}
}
},
};
const contentOptions = {
onMessage: async (messageEvent, experienceMetadata) => {
switch (messageEvent.eventName) {
case 'ERROR_OCCURRED': {
console.log("Do something when the embedded experience fails loading.");
break;
}
}
}
};
const embeddedConsoleExperience = await embeddingContext.embedConsole(frameOptions, contentOptions);
};
</script>
</head>
<body onload="embedSession()">
<div id="experience-container"></div>
</body>
</html>
- SDK 1.0
-
<!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 = {
// replace this dummy url with the one generated via embedding API
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>
For this example to work, make sure to use the Amazon QuickSight Embedding SDK to load the
embedded console session on your website using JavaScript. To get your copy, do one
of the following:
