Amazon QuickSight is a fully managed, cloud-native business intelligence (BI) service that makes it easy to connect to your data, create interactive dashboards and reports, and share these with tens of thousands of users, either within QuickSight or embedded in your application or website.
QuickSight recently launched a new major version of its Embedding SDK (v2.0) to improve developer experience when embedding QuickSight in your application or website. The QuickSight SDK v2.0 adds several customization improvements such as an optional preloader and new external hooks for managing undo, redo, print options, and parameters. Additionally, there are major rewrites to deliver developer-focused improvements, including static type checking, enhanced runtime validation, strong consistency in call patterns, and optimized event chaining.
The new SDK supports improved code completion when integrated with IDEs through its adoption of TypeScript and the newly introduced
contentOptions, which segment embedding options into parameters unified for all embedding experiences and parameters unique for each embedding experience, respectively. Additionally, SDK v2.0 offers increased visibility by providing new experience-specific information and warnings within the SDK. This increases transparency, and developers can monitor and handle new content states.
The QuickSight SDK v2.0 is modernized by using promises for all actions, so developers can use async and await functions for better event management. Actions are further standardized to return a response for both data requesting and non-data requesting actions, so developers have full visibility to the end-to-end application handshake.
In addition to the new SDK, we are also introducing state persistence for user-based dashboard and console embedding. The
GenerateEmbedUrlForRegisteredUser API is updated to support this feature and improves end-user experience and interactivity on embedded content.
SDK Feature overview
The QuickSight SDK v2.0 offers new functionalities along with elevating developers’ experience. The following functionalities have been added in this version:
- Dashboard undo, redo, and reset actions can now be invoked from the application
- A loading animation can be added to the dashboard container while the contents of the dashboard are loaded
- Frame creation, mounting, and failure are communicated as change events that can be used by the application
setParameter()values are unified, eliminating additional data transformations
Using the new SDK
The embed URL obtained using the
GenerateEmbedUrlForAnonymousUser APIs can be consumed in the application using the
embedDashboard experience in SDK v2.0. This method takes two parameters:
- frameOptions – This is a required parameter, and its properties determine the container options to embed a dashboard:
- url – The embed URL generated using
- container – The parent
HTMLElementto embed the dashboard
- url – The embed URL generated using
- contentOptions – This is an optional parameter that controls the dashboard locale and captures events from the SDK.
The following sample code uses the preceding parameters to embed a dashboard:
Render a loading animation while the dashboard loads
SDK v2.0 allows an option to render a loading animation in the iFrame container while the dashboard loads. This improves user experience by suggesting resource loading is in progress and where it will appear, and eliminates any perceived latency.
You can enable a loading animation by using the
withIframePlaceholder option in the
This option is supported by all embedding experiences.
Monitor changes in SDK code status
SDK v2.0 supports a new callback
onChange, which returns
eventNames along with corresponding
eventCodes to indicate errors, warnings, or information from the SDK.
You can use the events returned by the callback to monitor frame creation status and code status returned by the SDK. For example, if the SDK returns an error when an invalid embed URL is used, you can use a placeholder text or image in place of the embedded experience to notify the user.
eventCodes are returned as part of the
onChange callback when there is a change in the SDK code status.
See the following code:
Monitor interactions in embedded dashboards
Another callback supported by SDK v2.0 is
onMessage, which returns information about specific events within an embedded experience. The
eventName returned depends on the type of embedding experience used and allows application developers to invoke custom code for specific events.
For example, you can monitor if an embedded dashboard is fully loaded or invoke a custom function that logs the parameter values end-users set or change within the dashboard. Your application can now work seamlessly with SDK v2.0 to track and react to interactions within an embedded experience.
eventNames returned are specific to the embedding experience used. The following
eventNames are for the dashboard embedding experience. For additional
eventNames, visit the GitHub repo.
See the following code:
Initiate dashboard print from the application
The new SDK version supports initiating undo, redo, reset, and print from the parent application, without having to add the native embedded QuickSight navbar. This allows developers flexibility to add custom buttons or application logic to control and invoke these options.
For example, you can add a standalone button in your application that allows end-users to print an embedded dashboard, without showing a print icon or navbar within the embedded frame. This can be done using the
The following code sample shows a loading animation, SDK code status, and dashboard interaction monitoring, along with initiating dashboard print from the application:
In addition to the new SDK, QuickSight now supports state persistence for dashboard and console embedding. State Persistance means when readers slice and dice embedded dashboards with filters, QuickSight will persist filter selection until they return to the dashboard. Readers can pick up where they left off and don’t have to re-select filters.
State persistence is currently supported only for the user-based (not anonymous) dashboard and console embedding experience.
You can enable state persistence using the
FeatureConfigurations parameter in the
StatePersistence structure that can be customized by setting
The API structure is below:
The following code disables state persistence for QuickSight console embedding:
Note the following when using these features:
- For dashboard embedding, state persistence is disabled by default. To enable this feature, set
- For console embedding, state persistence is enabled by default. To disable this feature, set
With the latest iteration of the QuickSight Embedding SDK, you can indicate when an embedded experience is loading, monitor and respond to errors from the SDK, observe changes and interactivity, along with invoking undo, redo, reset, and print actions from application code.
Additionally, you can enable state persistence to persist filter selection for readers and allow them to pick up where they left off when revisiting an embedded dashboard.
For more detailed information about the SDK and experience-specific options, visit the GitHub repo.
About the authors
Raj Jayaraman is a Senior Specialist Solutions Architect for Amazon QuickSight. Raj focuses on helping customers develop sample dashboards, embed analytics and adopt BI design patterns and best practices.
Mayank Agarwal is a product manager for Amazon QuickSight, AWS’ cloud-native, fully managed BI service. He focuses on account administration, governance and developer experience. He started his career as an embedded software engineer developing handheld devices. Prior to QuickSight he was leading engineering teams at Credence ID, developing custom mobile embedded device and web solutions using AWS services that make biometric enrollment and identification fast, intuitive, and cost-effective for Government sector, healthcare and transaction security applications.
Rohit Pujari is the Head of Product for Embedded Analytics at QuickSight. He is passionate about shaping the future of infusing data-rich experiences into products and applications we use every day. Rohit brings a wealth of experience in analytics and machine learning from having worked with leading data companies, and their customers. During his free time, you can find him lining up at the local ice cream shop for his second scoop.