Step 3: Embed the Q search bar URL - Amazon QuickSight

Step 3: Embed the Q search bar URL

Note

The embedded QuickSight Q search bar provides the classic QuickSight Q&A experience. QuickSight integrates with Amazon Q Business to launch a new Generative Q&A experience. Developers are recommended to use the new Generative Q&A experience. For more information on the embedded Generative Q&A experience, see Embed the Amazon Q in QuickSight Generative Q&A experience.

In the following section, you can find how to embed the Q search bar URL from step 3 in your website or application page. You do this with the Amazon QuickSight embedding SDK (JavaScript). With the SDK, you can do the following:

  • Place the Q search bar on an HTML page.

  • Pass parameters into the Q search bar.

  • Handle error states with messages that are customized to your application.

To generate the URL that you can embed in your app, call the GenerateEmbedUrlForRegisteredUser API operation. 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 value 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/q/search...", "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713" }

Embed the Q search bar 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.

To do this, make sure that the domain to host the embedded Q search bar is on the allow list, the list of approved domains for your QuickSight subscription. This requirement protects your data by keeping unapproved domains from hosting embedded dashboards. For more information about adding domains for an embedded Q search bar, see Managing domains and embedding.

When you use the QuickSight Embedding SDK, the Q search bar on your page is dynamically resized based on the state. By using the QuickSight Embedding SDK, you can also control parameters within the Q search bar and receive callbacks in terms of page load completion and errors.

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>Q Search Bar 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 embedQSearchBar = 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 = { hideTopicName: false, theme: '<YOUR_THEME_ID>', allowTopicSelection: true, onMessage: async (messageEvent, experienceMetadata) => { switch (messageEvent.eventName) { case 'Q_SEARCH_OPENED': { console.log("Do something when Q Search content expanded"); break; } case 'Q_SEARCH_CLOSED': { console.log("Do something when Q Search content collapsed"); break; } case 'Q_SEARCH_SIZE_CHANGED': { console.log("Do something when Q Search size changed"); break; } case 'CONTENT_LOADED': { console.log("Do something when the Q Search is loaded."); break; } case 'ERROR_OCCURRED': { console.log("Do something when the Q Search fails loading."); break; } } } }; const embeddedDashboardExperience = await embeddingContext.embedQSearchBar(frameOptions, contentOptions); }; </script> </head> <body onload="embedQSearchBar()"> <div id="experience-container"></div> </body> </html>
SDK 1.0
<!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 onOpen() { console.log("Do something when the Q search bar opens"); } function onClose() { 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: onOpen, collapseCallback: onClose, iconDisabled: false, topicNameDisabled: false, themeId: 'bdb844d0-0fe9-4d9d-b520-0fe602d93639', 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>

For this example to work, make sure to use the Amazon QuickSight Embedding SDK to load the embedded dashboard on your website using JavaScript. To get your copy, do one of the following: