Improve your analytics embedding expertise with the brand new Amazon QuickSight JavaScript SDK

March 10, 2023

1

Amazon QuickSight is a totally managed, cloud-native enterprise intelligence (BI) service that makes it straightforward to connect with your knowledge, create interactive dashboards and reviews, and share these with tens of 1000’s of customers, both inside QuickSight or embedded in your utility or web site.

QuickSight just lately launched a brand new main model of its Embedding SDK (v2.0) to enhance developer expertise when embedding QuickSight in your utility or web site. The QuickSight SDK v2.0 provides a number of customization enhancements similar to an optionally available preloader and new exterior hooks for managing undo, redo, print choices, and parameters. Moreover, there are main rewrites to ship developer-focused enhancements, together with static sort checking, enhanced runtime validation, robust consistency in name patterns, and optimized occasion chaining.

The brand new SDK helps improved code completion when built-in with IDEs by way of its adoption of TypeScript and the newly launched frameOptions and contentOptions, which phase embedding choices into parameters unified for all embedding experiences and parameters distinctive for every embedding expertise, respectively. Moreover, SDK v2.0 presents elevated visibility by offering new experience-specific data and warnings throughout the SDK. This will increase transparency, and builders can monitor and deal with new content material states.

The QuickSight SDK v2.0 is modernized through the use of guarantees for all actions, so builders can use async and await features for higher occasion administration. Actions are additional standardized to return a response for each knowledge requesting and non-data requesting actions, so builders have full visibility to the end-to-end utility handshake.

Along with the brand new SDK, we’re additionally introducing state persistence for user-based dashboard and console embedding. The GenerateEmbedUrlForRegisteredUser API is up to date to assist this characteristic and improves end-user expertise and interactivity on embedded content material.

SDK Function overview

The QuickSight SDK v2.0 presents new functionalities together with elevating builders’ expertise. The next functionalities have been added on this model:

Dashboard undo, redo, and reset actions can now be invoked from the appliance
A loading animation might be added to the dashboard container whereas the contents of the dashboard are loaded
Body creation, mounting, and failure are communicated as change occasions that can be utilized by the appliance
Actions getParameter() values and setParameter() values are unified, eliminating extra knowledge transformations

Utilizing the brand new SDK

The embed URL obtained utilizing the GenerateEmbedUrlForRegisteredUser or GenerateEmbedUrlForAnonymousUser APIs might be consumed within the utility utilizing the embedDashboard expertise in SDK v2.0. This technique takes two parameters:

frameOptions – It is a required parameter, and its properties decide the container choices to embed a dashboard:
- url – The embed URL generated utilizing GenerateEmbedUrlForRegisteredUser or GenerateEmbedUrlForAnonymousUser APIs
- container – The mum or dad HTMLElement to embed the dashboard
contentOptions – That is an optionally available parameter that controls the dashboard locale and captures occasions from the SDK.

The next pattern code makes use of the previous parameters to embed a dashboard:

<html>
    <head>
        <!-- ... -->
        <script src=”https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js"></script>
        <!-- ... -->
        <script>
            (async () => {
                const {
                    createEmbeddingContext,
                } = window.QuickSightEmbedding;
                
                const embeddingContext = await createEmbeddingContext();
                
                const frameOptions = {
                    url: '<YOUR_EMBED_URL>',
                    container: '#your-embed-container'
                };
                
                const contentOptions = {
                    toolbarOptions: {
                        reset: true,
                        undoRedo: true,
                    }
                };
                
                embeddedDashboard = await EmbeddingContext.embedDashboard(frameOptions, contentOptions);                
            })();
        </script>
    </head>
    <physique>
        <div id="your-embed-container"></div>
    </physique>
</html>

Render a loading animation whereas the dashboard masses

SDK v2.0 permits an choice to render a loading animation within the iFrame container whereas the dashboard masses. This improves consumer expertise by suggesting useful resource loading is in progress and the place it’s going to seem, and eliminates any perceived latency.

You possibly can allow a loading animation through the use of the withIframePlaceholder choice within the frameOption parameter:

const frameOptions = {
           url: '<YOUR_EMBED_URL>',
            container: '#your-embed-container',            
            withIframePlaceholder: true
}

This selection is supported by all embedding experiences.

Monitor adjustments in SDK code standing

SDK v2.0 helps a brand new callback onChange, which returns eventNames together with corresponding eventCodes to point errors, warnings, or data from the SDK.

You need to use the occasions returned by the callback to watch body creation standing and code standing returned by the SDK. For instance, if the SDK returns an error when an invalid embed URL is used, you need to use a placeholder textual content or picture rather than the embedded expertise to inform the consumer.

The next eventNames and eventCodes are returned as a part of the onChange callback when there’s a change within the SDK code standing.

eventName	eventCode
ERROR	`FRAME_NOT_CREATED`: Invoked when the creation of the iframe aspect failed
	`NO_BODY`: Invoked when there isn’t a physique aspect within the internet hosting HTML
	`NO_CONTAINER`: Invoked when the expertise container is just not discovered
	`NO_URL`: Invoked when no URL is offered within the frameOptions
	`INVALID_URL`: Invoked when the URL offered is just not a legitimate URL for the expertise
INFO	`FRAME_STARTED`: Invoked simply earlier than the iframe is created
	`FRAME_MOUNTED`: Invoked after the iframe is appended into the expertise container
	`FRAME_LOADED`: Invoked after the iframe aspect emitted the load occasion
WARN	`UNRECOGNIZED_CONTENT_OPTIONS`: Invoked when the content material choices for the expertise include unrecognized properties
WARN	`UNRECOGNIZED_EVENT_TARGET`: Invoked when a message with an unrecognized occasion goal is acquired

See the next code:

const frameOptions = {
            url: '<YOUR_EMBED_URL>',
            container: '#your-embed-container',            
            withIframePlaceholder: true
            onChange: (changeEvent, metadata) => {
                change (changeEvent.eventName) {
                    case 'ERROR': {
                        doc.getElementById("your-embed-container").append('Unable to load Dashboard right now.');
                        break;
                    }
                }
            }
        }

Monitor interactions in embedded dashboards

One other callback supported by SDK v2.0 is onMessage, which returns details about particular occasions inside an embedded expertise. The eventName returned will depend on the kind of embedding expertise used and permits utility builders to invoke customized code for particular occasions.

For instance, you possibly can monitor if an embedded dashboard is absolutely loaded or invoke a customized perform that logs the parameter values end-users set or change throughout the dashboard. Your utility can now work seamlessly with SDK v2.0 to trace and react to interactions inside an embedded expertise.

The eventNames returned are particular to the embedding expertise used. The next eventNames are for the dashboard embedding expertise. For extra eventNames, go to the GitHub repo.

CONTENT_LOADED
ERROR_OCCURRED
PARAMETERS_CHANGED
SELECTED_SHEET_CHANGED
SIZE_CHANGED
MODAL_OPENED

See the next code:

const contentOptions = {
                    onMessage: async (messageEvent, experienceMetadata) => {
                        change (messageEvent.eventName) {
                            case 'PARAMETERS_CHANGED': {
                                ….. // Customized code
                                break;
                            }
…
}

Provoke dashboard print from the appliance

The brand new SDK model helps initiating undo, redo, reset, and print from the mum or dad utility, with out having so as to add the native embedded QuickSight navbar. This permits builders flexibility so as to add customized buttons or utility logic to manage and invoke these choices.

For instance, you possibly can add a standalone button in your utility that enables end-users to print an embedded dashboard, with out displaying a print icon or navbar throughout the embedded body. This may be achieved utilizing the initiatePrint motion:

embeddedDashboard.initiatePrint();

The next code pattern exhibits a loading animation, SDK code standing, and dashboard interplay monitoring, together with initiating dashboard print from the appliance:

<!DOCTYPE html>
<html lang="en">
  <head>
    <script src=" https://unpkg.com/amazon-quicksight-embedding-sdk@2.0.0/dist/quicksight-embedding-js-sdk.min.js "></script>
    <title>Embedding demo</title>

    <script>
      $(doc).prepared(perform() {

        var embeddedDashboard;

        doc.getElementById("print_button").onclick = perform printDashboard() {
            embeddedDashboard.initiatePrint();
        }

        perform embedDashboard(embedUrl) {
          const {
            createEmbeddingContext
          } = window.QuickSightEmbedding;
          (async () => {
            const embeddingContext = await createEmbeddingContext();
            const messageHandler = (messageEvent) => {
              change (messageEvent.eventName) {
                case 'CONTENT_LOADED': {
                  doc.getElementById("print_button").model.show="block";
                  break;
                }
                case 'ERROR_OCCURRED': {
                  console.log('Error occurred', messageEvent.message);
                  break;
                }
                case 'PARAMETERS_CHANGED': {
                  // Customized code..
                  break;
                }
              }
            }
            const frameOptions = {
      url: '<YOUR_EMBED_URL>',
              container: doc.getElementById("dashboardContainer"),
              width: "100%",
              peak: "AutoFit",
              loadingHeight: "200px",
              withIframePlaceholder: true,
              onChange: (changeEvent, metadata) => {
                change (changeEvent.eventName) {
                  case 'ERROR': {
                    doc.getElementById("dashboardContainer").append('Unable to load Dashboard right now.');
                    break;
                  }
                }
              }
            }
            const contentOptions = {
              locale: "en-US",
              onMessage: messageHandler
            }
            embeddedDashboard = await embeddingContext.embedDashboard(frameOptions, contentOptions);
          })();
        }
      });
    </Script>
  </head>
  <physique>
    <div>
       <button sort="button" id="print_button" model="show:none;">Print</button> 
    </div>
    <div id="dashboardContainer"></div>
  </physique>
</html>

State persistence

Along with the brand new SDK, QuickSight now helps state persistence for dashboard and console embedding. State Persistance means when readers slice and cube embedded dashboards with filters, QuickSight will persist filter choice till they return to the dashboard. Readers can decide up the place they left off and don’t should re-select filters.

State persistence is presently supported just for the user-based (not nameless) dashboard and console embedding expertise.

You possibly can allow state persistence utilizing the FeatureConfigurations parameter within the GenerateEmbedUrlForRegisteredUser API. FeatureConfigurations accommodates StatePersistence construction that may be personalized by setting Enabled as true or false.

The API construction is beneath:

generate-embed-url-for-registered-user
	aws-account-id <worth>
	[session-lifetime-in-minutes <value>]
	user-arn <worth>
	[cli-input-json | cli-input-yaml]
	[allowed-domains <value>]
	[generate-cli-skeleton <value>]
	experience-configuration <worth>
		Dashboard
			InitialDashboardId <worth>
			[FeatureConfigurations]
				[StatePersistence]
					Enabled <worth>
		QuickSightConsole
			InitialPath <worth>
			[FeatureConfigurations]
				[StatePersistence]
					Enabled <worth>

The next code disables state persistence for QuickSight console embedding:

aws quicksight generate-embed-url-for-registered-user 
--aws-account-id <AWS_Account_ID> 
--user-arn arn:aws:quicksight:us-east-1:<AWS_Account_ID>:consumer/<Namespace>/<QuickSight_User_Name>
--experience-configuration '{"QuickSightConsole": {
"InitialPath": "/begin/analyses",
"FeatureConfigurations": {"StatePersistence": {"Enabled": false}}}}' 
--region <Area>

The next code allows state persistence for QuickSight dashboard embedding:

aws quicksight generate-embed-url-for-registered-user 
--aws-account-id <AWS_Account_ID> 
--user-arn arn:aws:quicksight:us-east-1:<AWS_Account_ID>:consumer/<Namespace>/<QuickSight_User_Name>
--experience-configuration '{"Dashboard": {
"InitialDashboardId": “<Dashboard_ID>",
"FeatureConfigurations": {"StatePersistence": {"Enabled": true}}}}' 
--region <Area>

Issues

Notice the next when utilizing these options:

For dashboard embedding, state persistence is disabled by default. To allow this characteristic, set Enabled parameter in StatePersistence to true.
For console embedding, state persistence is enabled by default. To disable this characteristic, set Enabled parameter in StatePersistence to false.

Conclusion

With the newest iteration of the QuickSight Embedding SDK, you possibly can point out when an embedded expertise is loading, monitor and reply to errors from the SDK, observe adjustments and interactivity, together with invoking undo, redo, reset, and print actions from utility code.

Moreover, you possibly can allow state persistence to persist filter choice for readers and permit them to choose up the place they left off when revisiting an embedded dashboard.

For extra detailed details about the SDK and experience-specific choices, go to the GitHub repo.

Concerning the authors

Raj Jayaraman is a Senior Specialist Options Architect for Amazon QuickSight. Raj focuses on serving to clients develop pattern dashboards, embed analytics and undertake BI design patterns and greatest practices.

Mayank Agarwal is a product supervisor for Amazon QuickSight, AWS’ cloud-native, absolutely managed BI service. He focuses on account administration, governance and developer expertise. He began his profession as an embedded software program engineer growing handheld gadgets. Previous to QuickSight he was main engineering groups at Credence ID, growing customized cellular embedded machine and internet options utilizing AWS providers that make biometric enrollment and identification quick, intuitive, and cost-effective for Authorities sector, healthcare and transaction safety purposes.

Rohit Pujari is the Head of Product for Embedded Analytics at QuickSight. He’s captivated with shaping the way forward for infusing data-rich experiences into merchandise and purposes we use day by day. Rohit brings a wealth of expertise in analytics and machine studying from having labored with main knowledge firms, and their clients. Throughout his free time, you’ll find him lining up on the native ice cream store for his second scoop.

Supply hyperlink

Previous articleHave a good time Pi Day With Cisco Studying (We’re Saving You a Slice)

Next articleEvolving picture recognition with Geometric Deep Studying

Improve your analytics embedding expertise with the brand new Amazon QuickSight JavaScript SDK

SDK Function overview

Utilizing the brand new SDK

Render a loading animation whereas the dashboard masses

Monitor adjustments in SDK code standing

Monitor interactions in embedded dashboards

Provoke dashboard print from the appliance

State persistence

Issues

Conclusion

Concerning the authors

Learn how to Study Machine Studying On-line?

First Lake Database for Reside Search, SQL, and Gen AI Analytics

Generative AI and the authorized panorama: Evolving laws and implications

LEAVE A REPLY Cancel reply

Most Popular

ios – TabView web page change with button click on does not work in swift ui

PVR INOX Passport Month-to-month Subscription Go Launched at Rs. 699 for 10 Motion pictures

Morpho butterfly nanostructure conjures up expertise for vivid, balanced lighting

WellSaid Labs AI Voice Generator Overview (October 2023)

Recent Comments

ABOUT US

POPULAR POSTS

ios – TabView web page change with button click on does not work in swift ui

PVR INOX Passport Month-to-month Subscription Go Launched at Rs. 699 for 10 Motion pictures

Morpho butterfly nanostructure conjures up expertise for vivid, balanced lighting

POPULAR CATEGORY