amazon quicksight embedding sdk
1.0.0
Thank you for using the Amazon QuickSight JavaScript SDK. You can use this SDK to embed Amazon QuickSight in your HTML.
For more information and to learn how to use QuickSight Embedding, please visit QuickSight Developer Portal Website
Amazon QuickSight offers four different embedding experiences with options for user isolation with namespaces, and custom UI permissions.
Option 1: Use the Amazon QuickSight Embedding SDK in the browser:
...
<script src="https://unpkg.com/[email protected]/dist/quicksight-embedding-js-sdk.min.js">script>
<script type="text/javascript">
const onLoad = async () => {
const embeddingContext = await QuickSightEmbedding.createEmbeddingContext();
//...
};
script>
...
<body onload="onLoad()">
...Option 2: Install the Amazon QuickSight Embedding SDK in NodeJs:
npm install amazon-quicksight-embedding-sdkand then use it in your code using require syntax
const QuickSightEmbedding = require("amazon-quicksight-embedding-sdk");
const embeddingContext = await QuickSightEmbedding.createEmbeddingContext();or, using named import syntax:
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';
const embeddingContext = await createEmbeddingContext();or, using wildcard import syntax:
import * as QuickSightEmbedding from 'amazon-quicksight-embedding-sdk';
const embeddingContext = await QuickSightEmbedding.createEmbeddingContext();
Use createEmbeddingContext method to create an embedding context. It returns a promise of EmbeddingContext type.
export type CreateEmbeddingContext = (frameOptions?: EmbeddingContextFrameOptions) => Promise<EmbeddingContext>
export type EventListener = (
event: EmbeddingEvents,
metadata?: ExperienceFrameMetadata
) => void;
export type EmbeddingContextFrameOptions = {
onChange?: EventListener;
};
export type IEmbeddingContext = {
embedDashboard: (frameOptions: FrameOptions, contentOptions?: DashboardContentOptions) => Promise<DashboardExperience>;
embedVisual: (frameOptions: FrameOptions, contentOptions?: VisualContentOptions) => Promise<VisualExperience>;
embedConsole: (frameOptions: FrameOptions, contentOptions?: ConsoleContentOptions) => Promise<ConsoleExperience>;
embedQSearchBar: (frameOptions: FrameOptions, contentOptions?: QSearchContentOptions) => Promise<QSearchExperience>;
embedGenerativeQnA: (frameOptions: FrameOptions, contentOptions?: GenerativeQnAContentOptions) => Promise<GenerativeQnAContentOptions>;
};You can create the embedding context by calling createEmbeddingContext method without any arguments
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';
const embeddingContext: EmbeddingContext = await createEmbeddingContext();or, you can pass an object argument with onChange property
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';
const embeddingContext: EmbeddingContext = await createEmbeddingContext({
onChange: (changeEvent) => {
console.log('Context received a change', changeEvent);
},
});The embedding context creates an additional zero-pixel iframe and appends it into the body element on the page to centralize communication between the SDK and the embedded QuickSight content.
An EmbeddingContext instance exposes 4 experience methods
These methods take 2 parameters:
import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';
const embeddingContext = await createEmbeddingContext();
const {
embedDashboard,
embedVisual,
embedConsole,
embedQSearchBar,
} = embeddingContext;
const frameOptions = {
//...
};
const contentOptions = {
//...
};
// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);
// Embedding a visual experience
const embeddedVisualExperience = await embedVisual(frameOptions, contentOptions);
// Embedding a console experience
const embeddedConsoleExperience = await embedConsole(frameOptions, contentOptions);
// Embedding a Q search bar experience
const embeddedQSearchExperience = await embedQSearchBar(frameOptions, contentOptions);
frameOptions for All Embedding Experiences
This is the embed URL you have generated using the QuickSight API Operations for Embedding.
Follow Embedding with the QuickSight API in the Amazon QuickSight User Guide to generate the url.
For each experience, you need to make sure that the users are granted the necessary permissions to view the embedded experience.
This is the parent HTMLElement where we're going to embed QuickSight.
It can be an HTMLElement:
container: document.getElementById("experience-container")Or, it can be a query selector string:
container: "#experience-container"You can set width for the iframe that holds your embedded QuickSight experience. You can set it to be a fixed value:
width: "1000px"Or, a relative value:
width: "60%"To make your embedded QuickSight experience responsive, don't set it (leave them at the default: 100%). Then you can make the container HTMLElement responsive to screen size change.
You can set height for the iframe that holds your embedded QuickSight experience. You can set it to be a fixed value:
height: "700px"Or, a relative value:
height: "80%"To make your embedded QuickSight experience responsive, don't set it (leave them at the default: 100%). Then you can make the container HTMLElement responsive to screen size change.
You can customize style of the iframe that holds your embedded experience by one of the followings:
.quicksight-embedding-iframe {
margin: 5px;
}
className property:.your-own-class {
margin: 5px;
}
const option = { 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.
It renders a simple spinner in the embedded experience container while the contents of the embedding experience iframe is being loaded.
This callback is invoked when there is a change in the SDK code status.
export type EventListener = (event: EmbeddingEvents, metadata?: ExperienceFrameMetadata) => void;
export interface ChangeEvent {
eventName: EventName,
eventLevel: ChangeEventLevel,
message?: EventMessageValue,
data?: EventData
}
export type ExperienceFrameMetadata = {
frame: EmbeddingIFrameElement | null;
};
Supported eventLevels:
ERROR
INFO
WARN
ErrorChangeEventNames
NO_FRAME_OPTIONS = 'NO_FRAME_OPTIONS',
INVALID_FRAME_OPTIONS = 'INVALID_FRAME_OPTIONS',
FRAME_NOT_CREATED: invoked when the creation of the iframe element failed
NO_BODY: invoked when there is no `body` element in the hosting html
NO_CONTAINER: invoked when the experience container is not found
INVALID_CONTAINER: invoked when the container provided is not a valid DOM node
NO_URL: invoked when no url is provided in the frameOptions
INVALID_URL: invoked when the url provided is not a valid url for the experience
NO_FRAME_OPTIONS: invoked when frameOptions property is not populated,
INVALID_FRAME_OPTIONS: invoked when the frameOptions value is not object type,
InfoChangeEventNames
FRAME_STARTED: invoked just before the iframe is created
FRAME_MOUNTED: invoked after the iframe is appended into the experience container
FRAME_LOADED: invoked after iframe element emited the `load` event
FRAME_REMOVED: invoked after iframe element is removed from the DOM
WarnChangeEventNames
UNRECOGNIZED_CONTENT_OPTIONS: invoked when the content options for the experience contain unrecognized properties
UNRECOGNIZED_FRAME_OPTIONS: invoked when the frame options for the experience contain unrecognized properties
UNRECOGNIZED_EVENT_TARGET: invoked when a message with unrecognized event target is received
const frameOptions = {
//...
onChange: (changeEvent: EmbeddingEvents, metadata: ExperienceFrameMetadata) => {
if (changeEvent.eventLevel === 'ERROR') {
console.log(`Do something when embedding experience failed with "${changeEvent.eventName}"`);
return;
}
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;
}
case 'FRAME_REMOVED': {
console.log("Do something when the experience frame is removed.");
break;
}
//...
}
},
};
contentOptions for All Embedding Experiences
You can set locale for the embedded QuickSight session:
const option = { 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),
ja-JP (日本語),
ko-KR (한국어),
zh-CN (中文 (简体)),
zh-TW (中文 (繁體))
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 add onMessage callback into the contentOptions of all embedding experiences.
export type EventListener = (event: EmbeddingEvents, metadata?: ExperienceFrameMetadata) => void;
export interface SimpleMessageEvent {
eventName: EventName;
message?: EventMessageValue;
data?: EventData;
eventTarget?: InternalExperiences;
}
export type ExperienceFrameMetadata = {
frame: EmbeddingIFrameElement | null;
};See the experience specific documentation below for the supported eventNames for each experience type.
const contentOptions = {
//...
onMessage: async (messageEvent: EmbeddingEvents, metadata?: ExperienceFrameMetadata) => {
switch (messageEvent.eventName) {
case 'CONTENT_LOADED': {
console.log("Do something when the embedded experience is fully loaded.");
break;
}
case 'ERROR_OCCURRED': {
console.log("Do something when the embedded experience fails loading.");
break;
}
//...
}
}
};
Dashboard Embedding provides an interactive read-only experience. The level of interactivity is set when the dashboard is published.
For more information, see Working with embedded analytics in the Amazon QuickSight User Guide.
Use embedDashboard method to embed a QuickSight dashboard. It returns a promise of DashboardExperience type.
export class DashboardExperience extends BaseExperience<DashboardContentOptions, InternalDashboardExperience, IDashboardExperience, TransformedDashboardContentOptions, DashboardExperienceFrame> {
initiatePrint: () => Promise<SuccessResponseMessage | ErrorResponseMessage>;
undo: () => Promise<SuccessResponseMessage | ErrorResponseMessage>;
redo: () => Promise<SuccessResponseMessage | ErrorResponseMessage>;
toggleBookmarksPane: () => Promise<SuccessResponseMessage | ErrorResponseMessage>;
getParameters: () => Promise<Parameter[]>;
getSheets: () => Promise<Sheet[]>;
getVisualActions: (sheetId: string, visualId: string) => Promise<VisualAction[]>;
addVisualActions: (sheetId: string, visualId: string, actions: VisualAction[]) => Promise<SuccessResponseMessage | ErrorResponseMessage>;
setVisualActions: (sheetId: string, visualId: string, actions: VisualAction[]) => Promise<SuccessResponseMessage | ErrorResponseMessage>;
getFilterGroupsForSheet: (sheetId: string) => Promise<FilterGroup[]>;
getFilterGroupsForVisual: (sheetId: string, visualId: string) => Promise<FilterGroup[]>;
addFilterGroups: (filterGroups: FilterGroup[]) => Promise<SuccessResponseMessage | ErrorResponseMessage>;
updateFilterGroups: (filterGroups: FilterGroup[]) => Promise<SuccessResponseMessage | ErrorResponseMessage>;
removeFilterGroups: (filterGroupsOrIds: FilterGroup[] | string[]) => Promise<SuccessResponseMessage | ErrorResponseMessage>;
setTheme:(themeArn: string) => Promise<SuccessResponseMessage | ErrorResponseMessage>;
setThemeOverride: (themeOverride: ThemeConfiguration) => Promise<SuccessResponseMessage | ErrorResponseMessage>;
createSharedView: () => Promise<SuccessResponseMessage | ErrorResponseMessage>;
getSelectedSheetId: () => Promise<string>;
setSelectedSheetId: (sheetId: string) => Promise<SuccessResponseMessage | ErrorResponseMessage>;
navigateToDashboard: (dashboardId: string, navigateToDashboardOptions?: NavigateToDashboardOptions) => Promise<SuccessResponseMessage | ErrorResponseMessage>;
removeVisualActions: (sheetId: string, visualId: string, actions: VisualAction[]) => Promise<SuccessResponseMessage | ErrorResponseMessage>;
getSheetVisuals: (sheetId: string) => Promise<Visual[]>;
setParameters: (parameters: Parameter[]) => Promise<SuccessResponseMessage | ErrorResponseMessage>;
reset: () => Promise<SuccessResponseMessage | ErrorResponseMessage>;
send: <EventMessageValue extends EventMessageValues>(messageEvent: EmbeddingMessageEvent<MessageEventName>) => Promise<ResponseMessage<EventMessageValue>>;
}