diff --git a/docs/add-functionality/add-event.md b/docs/add-functionality/add-event.md index d93018e..6ce2e90 100644 --- a/docs/add-functionality/add-event.md +++ b/docs/add-functionality/add-event.md @@ -161,6 +161,48 @@ None embedDossier.registerEventHandler(EventType.ON_PAGE_LOADED, onPageLoadedHandler); ``` +### onEmbedPageLoaded + +#### Event enumeration + +`EventType.ON_EMBED_PAGE_LOADED` + +#### Description + +Raised every time the embedded page changes, for example, from the library page to dashboard pages or on dashboard pages switched. + +#### Content + +Object containing only one field, `pageType`, which indicates the embedded page type. + +Possible values for `pageType`: + +```js +const PAGE_TYPE = { + LIBRARY: "library", + DOSSIER: "dossier", + DOSSIER_CONSUMPTION: "dossierConsumption", + REPORT: "report", + REPORT_AUTHORING: "reportAuthoring", + BOT_CONSUMPTION: "botConsumption", + DOCUMENT_CONSUMPTION: "documentConsumption", +}; +``` + +#### Code example + +```js +embedDossier.registerEventHandler(EventType.ON_EMBED_PAGE_LOADED, onEmbedPageLoadedHandler); +``` + +#### Content example + +```json +{ + "pageType": "dossier" +} +``` + ### onLayoutChanged #### Event enumeration diff --git a/docs/embed-bot-consumption-page/add-agent-event.md b/docs/embed-bot-consumption-page/add-agent-event.md new file mode 100644 index 0000000..b8ae899 --- /dev/null +++ b/docs/embed-bot-consumption-page/add-agent-event.md @@ -0,0 +1,444 @@ +--- +title: Add agent event handling +description: + Agent events allow an embedded Strategy agent consumption page to communicate with the container + page. You can listen for agent events and provide handler functions to respond to user actions. +--- + +Agent events allow an embedded Strategy agent consumption page to communicate with the container page. +You can register agent event handlers to track user interactions, trigger custom workflows, or +synchronize your host application state. + +Once you have embedded the agent page by using +`microstrategy.embeddingContexts.embedBotConsumptionPage(props)`, you can use +`embeddingContext.registerEventHandler(evtName, handler)` to listen for events. + +## Agent event types + +Use the `AgentEventType` enumeration in your application code to register handlers. + +```js +const AgentEventType = { + ON_QUESTION_SUBMITTED: "onQuestionSubmitted", + ON_ANSWER_RECEIVED: "onAnswerReceived", + ON_ERROR: "onError", + ON_CONVERSATION_SWITCH: "onConversationSwitch", + ON_NEW_CHAT: "onNewChat", + ON_THUMBS_UP: "onThumbsUp", + ON_THUMBS_DOWN: "onThumbsDown", + ON_FOLLOW_UP: "onFollowUp", + ON_SOURCE_CLICK: "onSourceClick", + ON_CHAT_DELETED: "onChatDeleted", + ON_CLEAR_HISTORY: "onClearHistory", + ON_CLEAR_ALL_CHATS: "onClearAllChats", + ON_ASK_AGAIN: "onAskAgain", +}; +``` + +## Register and remove handlers + +Use `registerEventHandler` to bind a callback and `removeEventHandler` to unbind it. + +```js +const onQuestionSubmittedHandler = (content) => { + // Add your own logic here + console.log("Question submitted", content); +}; + +embeddingContext.registerEventHandler( + AgentEventType.ON_QUESTION_SUBMITTED, + onQuestionSubmittedHandler +); + +// Later, when cleanup is needed: +embeddingContext.removeEventHandler( + AgentEventType.ON_QUESTION_SUBMITTED, + onQuestionSubmittedHandler +); +``` + +## Events + +The following sections describe the supported agent events. + +### onQuestionSubmitted + +#### Event enumeration + +`AgentEventType.ON_QUESTION_SUBMITTED` + +#### Description + +Raised when a user submits a question to the agent. + +#### Content + +Object containing the submitted question context. + +#### Code example + +```js +embeddingContext.registerEventHandler( + AgentEventType.ON_QUESTION_SUBMITTED, + questionSubmittedHandler +); +``` + +#### Content example + +```json +{ + "text": "hi", + "conversationId": "21A1AD8B96364095BDF92FC1E297C75A" +} +``` + +### onAnswerReceived + +#### Event enumeration + +`AgentEventType.ON_ANSWER_RECEIVED` + +#### Description + +Raised when the agent receives an answer for a submitted question. + +#### Content + +Object containing answer metadata and answer body. + +#### Code example + +```js +embeddingContext.registerEventHandler(AgentEventType.ON_ANSWER_RECEIVED, answerReceivedHandler); +``` + +#### Content example + +```json +{ + "questionId": "B7CA92F04B9FAE8D941C3E9B7E0CD754:DC8E28DFF1C84F48AA4F56BA7368CFC4:1E4A24D905D14B469512A38513AC7469", + "answer": { + "text": "Hi, welcome back!" + } +} +``` + +### onError + +#### Event enumeration + +`AgentEventType.ON_ERROR` + +#### Description + +Raised when the agent flow encounters an error. + +#### Content + +Object containing `message` and `type`. + +#### Code example + +```js +embeddingContext.registerEventHandler(AgentEventType.ON_ERROR, errorHandler); +``` + +#### Content example + +```json +{ + "message": "{\"message\":\"Oops. Something went wrong. Please try again.\",\"details\":\"\"}", + "type": "question_streaming_error" +} +``` + +### onConversationSwitch + +#### Event enumeration + +`AgentEventType.ON_CONVERSATION_SWITCH` + +#### Description + +Raised when a user switches to another conversation. + +#### Content + +Object containing the current `conversationId`. + +#### Code example + +```js +embeddingContext.registerEventHandler( + AgentEventType.ON_CONVERSATION_SWITCH, + conversationSwitchHandler +); +``` + +#### Content example + +```json +{ + "conversationId": "1E4A24D905D14B469512A38513AC7469" +} +``` + +### onNewChat + +#### Event enumeration + +`AgentEventType.ON_NEW_CHAT` + +#### Description + +Raised when a user starts a new chat. + +#### Content + +Object containing the newly created conversation identifier. + +#### Code example + +```js +embeddingContext.registerEventHandler(AgentEventType.ON_NEW_CHAT, newChatHandler); +``` + +#### Content example + +```json +{ + "conversationId": "40C259C9854C4AC1A6C4D73721769D18" +} +``` + +### onThumbsUp + +#### Event enumeration + +`AgentEventType.ON_THUMBS_UP` + +#### Description + +Raised when a user gives positive feedback to an answer. + +#### Content + +Object containing `messageId`. + +#### Code example + +```js +embeddingContext.registerEventHandler(AgentEventType.ON_THUMBS_UP, thumbsUpHandler); +``` + +#### Content example + +```json +{ + "messageId": "B7CA92F04B9FAE8D941C3E9B7E0CD754:DC8E28DFF1C84F48AA4F56BA7368CFC4:1E4A24D905D14B469512A38513AC7469" +} +``` + +### onThumbsDown + +#### Event enumeration + +`AgentEventType.ON_THUMBS_DOWN` + +#### Description + +Raised when a user gives negative feedback to an answer. + +#### Content + +Object containing `messageId`. + +#### Code example + +```js +embeddingContext.registerEventHandler(AgentEventType.ON_THUMBS_DOWN, thumbsDownHandler); +``` + +#### Content example + +```json +{ + "messageId": "B7CA92F04B9FAE8D941C3E9B7E0CD754:DC8E28DFF1C84F48AA4F56BA7368CFC4:1E4A24D905D14B469512A38513AC7469" +} +``` + +### onFollowUp + +#### Event enumeration + +`AgentEventType.ON_FOLLOW_UP` + +#### Description + +Raised when a user clicks or sends a follow-up question. + +#### Content + +Object containing `messageId`. + +#### Code example + +```js +embeddingContext.registerEventHandler(AgentEventType.ON_FOLLOW_UP, followUpHandler); +``` + +#### Content example + +```json +{ + "messageId": "B7CA92F04B9FAE8D941C3E9B7E0CD754:DC8E28DFF1C84F48AA4F56BA7368CFC4:1E4A24D905D14B469512A38513AC7469" +} +``` + +### onSourceClick + +#### Event enumeration + +`AgentEventType.ON_SOURCE_CLICK` + +#### Description + +Raised when a user clicks a source reference in an answer. + +#### Content + +Object containing the clicked source metadata. + +#### Code example + +```js +embeddingContext.registerEventHandler(AgentEventType.ON_SOURCE_CLICK, sourceClickHandler); +``` + +#### Content example + +```json +{ + "sourceId": "6703BC33A1F74D3895FAE1403EB0401D", + "name": "AUTO_MD.md", + "url": "https://..." +} +``` + +### onChatDeleted + +#### Event enumeration + +`AgentEventType.ON_CHAT_DELETED` + +#### Description + +Raised when a user deletes a single chat conversation. + +#### Content + +Object containing the deleted conversation identifier. + +#### Code example + +```js +embeddingContext.registerEventHandler(AgentEventType.ON_CHAT_DELETED, chatDeletedHandler); +``` + +#### Content example + +```json +{ + "conversationId": "1E4A24D905D14B469512A38513AC7469" +} +``` + +### onClearHistory + +#### Event enumeration + +`AgentEventType.ON_CLEAR_HISTORY` + +#### Description + +Raised when a user clears the history inside the active conversation. + +#### Content + +Object containing the affected conversation identifier. + +#### Code example + +```js +embeddingContext.registerEventHandler(AgentEventType.ON_CLEAR_HISTORY, clearHistoryHandler); +``` + +#### Content example + +```json +{ + "conversationId": "1E4A24D905D14B469512A38513AC7469" +} +``` + +### onClearAllChats + +#### Event enumeration + +`AgentEventType.ON_CLEAR_ALL_CHATS` + +#### Description + +Raised when a user clears all chat conversations. + +#### Content + +Empty object. + +#### Code example + +```js +embeddingContext.registerEventHandler(AgentEventType.ON_CLEAR_ALL_CHATS, clearAllChatsHandler); +``` + +#### Content example + +```json +{} +``` + +### onAskAgain + +#### Event enumeration + +`AgentEventType.ON_ASK_AGAIN` + +#### Description + +Raised when a user triggers Ask Again on a previous question. + +#### Content + +Object containing `messageId`. + +#### Code example + +```js +embeddingContext.registerEventHandler(AgentEventType.ON_ASK_AGAIN, askAgainHandler); +``` + +#### Content example + +```json +{ + "messageId": "B7CA92F04B9FAE8D941C3E9B7E0CD754:DC8E28DFF1C84F48AA4F56BA7368CFC4:4C63C7442E4747D8AB74A96B2" +} +``` + +## Best practices + +- Register handlers after `embedBotConsumptionPage(props)` resolves. +- Remove handlers when your host view is unmounted or destroyed. +- Keep handlers lightweight and push long-running work to async tasks. +- Use `onError` to centralize fallback behavior and diagnostics. diff --git a/docs/embed-bot-consumption-page/embed-bot-consumption-page.md b/docs/embed-bot-consumption-page/embed-bot-consumption-page.md index 4505f86..3b829a2 100644 --- a/docs/embed-bot-consumption-page/embed-bot-consumption-page.md +++ b/docs/embed-bot-consumption-page/embed-bot-consumption-page.md @@ -1,11 +1,11 @@ --- -title: Embed Strategy bot consumption page -description: The Embedding SDK allows you to quickly integrate a Strategy bot consumption page into a web application in a responsive manner. +title: Embed Strategy agent consumption page +description: The Embedding SDK allows you to quickly integrate a Strategy agent consumption page into a web application in a responsive manner. --- -The Embedding SDK allows you to quickly integrate a Strategy bot consumption page into a web application in a responsive manner. +The Embedding SDK allows you to quickly integrate a Strategy agent consumption page into a web application in a responsive manner. -There are three basic steps for embedding a Strategy bot consumption page. +There are three basic steps for embedding a Strategy agent consumption page. 1. In the initial page of your web application, add a link to the Strategy JavaScript Embedding SDK. @@ -15,13 +15,13 @@ There are three basic steps for embedding a Strategy bot consumption page. Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual Library Server URL, e.g., [https://demo.microstrategy.com/MicroStrategyLibrary](https://demo.microstrategy.com/MicroStrategyLibrary). -1. Create a `
` as the placeholder where you want to embed the bot consumption page. +1. Create a `
` as the placeholder where you want to embed the agent consumption page. ```html
``` -1. Call the `microstrategy.embeddingContexts.embedBotConsumptionPage(props)` method to embed the bot consumption page in the container. +1. Call the `microstrategy.embeddingContexts.embedBotConsumptionPage(props)` method to embed the agent consumption page in the container. ```js microstrategy.embeddingContexts.embedBotConsumptionPage({ @@ -34,6 +34,10 @@ There are three basic steps for embedding a Strategy bot consumption page. To help you get started, we have provided a number of simple applications with sample code and explanations. -- [Properties for an embedded Strategy bot consumption page](./embed-bot-consumption-properties.md) +- [Properties for an embedded Strategy agent consumption page](./embed-bot-consumption-properties.md) - Describes the properties that can be set for an embedded Strategy bot consumption page. + Describes the properties that can be set for an embedded Strategy agent consumption page. + +- [Add agent event handling](./add-agent-event.md) + + Describes how to register event handlers for Strategy agent events. diff --git a/docs/embed-bot-consumption-page/embed-bot-consumption-properties.md b/docs/embed-bot-consumption-page/embed-bot-consumption-properties.md index 02cbe8b..22314ed 100644 --- a/docs/embed-bot-consumption-page/embed-bot-consumption-properties.md +++ b/docs/embed-bot-consumption-page/embed-bot-consumption-properties.md @@ -1,23 +1,23 @@ --- -title: Properties for an embedded Strategy bot consumption page -description: Describes the properties that can be set for an embedded Strategy bot consumption page. +title: Properties for an embedded Strategy agent consumption page +description: Describes the properties that can be set for an embedded Strategy agent consumption page. --- -When you embed a Strategy bot consumption page into a web page, you use the `embedBotConsumptionPage(props)` method under the `microstrategy.embeddingContexts` namespace. +When you embed a Strategy agent consumption page into a web page, you use the `embedBotConsumptionPage(props)` method under the `microstrategy.embeddingContexts` namespace. ## Method ### `microstrategy.embeddingContexts.embedBotConsumptionPage(props)` -This method creates an iFrame on the web page (in the location specified by the `placeholder` property) and inserts a link to the Strategy bot consumption page URL (specified by the `serverUrl` property). +This method creates an iFrame on the web page (in the location specified by the `placeholder` property) and inserts a link to the Strategy agent consumption page URL (specified by the `serverUrl` property). #### Return value -This method returns a promise, which is resolved when the Strategy bot consumption page is loaded. +This method returns a promise, which is resolved when the Strategy agent consumption page is loaded. #### Input parameters -The `props` parameter contains required key:value pairs that defines the Library Server URL and the `
` placeholder where the iFrame containing the Strategy bot consumption page will be created. It can also contain other optional key:value pairs to customize the UI, authentication and custom error handler. +The `props` parameter contains required key:value pairs that defines the Library Server URL and the `
` placeholder where the iFrame containing the Strategy agent consumption page will be created. It can also contain other optional key:value pairs to customize the UI, authentication and custom error handler. The `props` parameter could contain the following key:value pairs: @@ -48,7 +48,7 @@ microstrategy.embeddingContexts.embedBotConsumptionPage({ ### `serverUrl`, `projectId`, `objectId` -The required parameters in the bot URL. +The required parameters in the agent URL. These properties build the full report page URL to be embedded. The Embedding SDK builds the URL using `serverUrl` + '/app/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. @@ -74,7 +74,7 @@ microstrategy.embeddingContexts.embedBotConsumptionPage({ ### `customApplicationId`, `pageKey` -The optional parameters in the bot URL. +The optional parameters in the agent URL. Specifies the application and page that the user wants to show in the embedded page. @@ -368,10 +368,38 @@ microstrategy.embeddingContexts.embedBotConsumptionPage({ }); ``` +### `onBeforeSubmit` + +Use `onBeforeSubmit` to preprocess the question text before submitting it to the agent. + +#### Required? + +No + +#### Default value + +N/A + +#### Sample + +```js +microstrategy.embeddingContexts.embedBotConsumptionPage({ + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", + placeholder: document.getElementById("container"), + onBeforeSubmit: async ({ text, conversationId }) => { + /* Add any functionality before submitting the question */ + const updatedText = text; // Modify the text as needed. + return { text: updatedText }; + }, +}); +``` + ### `disableHyper` -Use the `disableHyper` boolean value to decide if the hyper extension should highlight the bot consumption page or not +Use the `disableHyper` boolean value to decide if the hyper extension should highlight the agent consumption page or not #### Required? @@ -395,13 +423,13 @@ microstrategy.embeddingContexts.embedBotConsumptionPage({ ### `customUi` -Specifies the custom UI settings on the embedded pages, including Library home page, bot consumption page，bot authoring page, and report consumption page. +Specifies the custom UI settings on the embedded pages, including Library home page, agent consumption page, agent authoring page, and report consumption page. #### Properties ##### `addToLibraryBanner` -Use the `addToLibraryBanner` object to customize the "Add To Library" banner on the Strategy bot consumption page. All detailed properties below are `Boolean`. +Use the `addToLibraryBanner` object to customize the "Add To Library" banner on the Strategy agent consumption page. All detailed properties below are `Boolean`. - `enabled` - Enable the Library "Add To Library" banner or not. If the banner is disabled in custom application, the true value wouldn’t take effect. @@ -410,33 +438,33 @@ Use the `addToLibraryBanner` object to customize the "Add To Library" banner on #### `theme` -Use the `theme` object to customize the "theme" in the Library including bot consumption page. All detailed properties below are `Boolean`. +Use the `theme` object to customize the "theme" in the Library including agent consumption page. All detailed properties below are `Boolean`. - `enabled` - Enable the Library "theme" colors or not. The value can be true or false. If the value isn't defined, the default is true. ##### `botConsumption` -Use the `botConsumption` object to customize UI of the bot consumption page. All detailed properties below are `Boolean`. +Use the `botConsumption` object to customize UI of the agent consumption page. All detailed properties below are `Boolean`. - `snapshot.enabled` - - Enable the snapshot panel on the bot consumption page or not. + - Enable the snapshot panel on the agent consumption page or not. - Default value: `true`. - `topicsPanel.enabled` - - Enable the topics panel on the bot consumption page or not. + - Enable the topics panel on the agent consumption page or not. - Default value is undefined, which falls back to true. - `navigationBar.enabled` - - Enable the navigation bar on the bot consumption page or not. + - Enable the navigation bar on the agent consumption page or not. - Default value: `false`. - `aiBot` - - Enable title bars, the snapshot panel, topics panel, chat panel(show clear history, show give topics, show welcome page bot image, should load history, should save to history) on the bot consumption page or not. + - Enable title bars, the snapshot panel, topics panel, chat panel(show clear history, show give topics, show welcome page agent image, should load history, should save to history) on the agent consumption page or not. - Default value is undefined, which falls back to the following: ```javascript @@ -462,16 +490,16 @@ Use the `botConsumption` object to customize UI of the bot consumption page. All } ``` -- `aiBot.titleBar.enabled`: This field specifies whether to enable the title bar of chat panel, snapshot panel and topic panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. However, it's ignored when the field isn't defined or defined as true. Only when the value is false, the title bars of panels are hidden. -- `aiBot.snapshotPanel.enabled`: This field specifies whether to enable the snapshot panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.topicsPanel.enabled`: This field specifies whether to enable the topic panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.showClearHistory`: This field specifies whether to show clear history in the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.showGiveTopics`: This field specifies whether to show give topics in the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.showWelcomePageBotImg`: This field specifies whether to show bot image in the welcome page of the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.showCopyBtn`: This field specifies whether to show copy button in the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. +- `aiBot.titleBar.enabled`: This field specifies whether to enable the title bar of chat panel, snapshot panel and topic panel on the agent consumption page or not. The value can be true or false. If this field isn't defined, the default is true. However, it's ignored when the field isn't defined or defined as true. Only when the value is false, the title bars of panels are hidden. +- `aiBot.snapshotPanel.enabled`: This field specifies whether to enable the snapshot panel on the agent consumption page or not. The value can be true or false. If this field isn't defined, the default is true. +- `aiBot.topicsPanel.enabled`: This field specifies whether to enable the topic panel on the agent consumption page or not. The value can be true or false. If this field isn't defined, the default is true. +- `aiBot.chatPanel.showClearHistory`: This field specifies whether to show clear history in the chat panel on the agent consumption page or not. The value can be true or false. If this field isn't defined, the default is true. +- `aiBot.chatPanel.showGiveTopics`: This field specifies whether to show give topics in the chat panel on the agent consumption page or not. The value can be true or false. If this field isn't defined, the default is true. +- `aiBot.chatPanel.showWelcomePageBotImg`: This field specifies whether to show agent image in the welcome page of the chat panel on the agent consumption page or not. The value can be true or false. If this field isn't defined, the default is true. +- `aiBot.chatPanel.showCopyBtn`: This field specifies whether to show copy button in the chat panel on the agent consumption page or not. The value can be true or false. If this field isn't defined, the default is true. - `aiBot.chatPanel.shouldExpandRelatedSuggestionsOnInit`: This field specifies whether to show the related suggestions list in the chat panel as expanded or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.shouldLoadHistory`: This field specifies whether to load chat history in the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.shouldSaveToHistory`: This field specifies whether to save chat history in the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. +- `aiBot.chatPanel.shouldLoadHistory`: This field specifies whether to load chat history in the chat panel on the agent consumption page or not. The value can be true or false. If this field isn't defined, the default is true. +- `aiBot.chatPanel.shouldSaveToHistory`: This field specifies whether to save chat history in the chat panel on the agent consumption page or not. The value can be true or false. If this field isn't defined, the default is true. #### Sample @@ -518,7 +546,7 @@ microstrategy.embeddingContexts.embedBotConsumptionPage({ ### `permissions` -Specify the permissions on the embedded bot consumption page. +Specify the permissions on the embedded agent consumption page. #### Required? @@ -528,7 +556,7 @@ No ##### `allowClipboardWrite` -To grant the "ClipboardWrite" permission or not. Could be used to enable the copy functionality on a bot message or not. It's worthy note that the copy functionality also requires the Library server to be HTTPS. If it's an HTTP server, the copy functionality would be disabled, regardless of the value of this flag. +To grant the "ClipboardWrite" permission or not. Could be used to enable the copy functionality on an agent message or not. It's worth noting that the copy functionality also requires the Library server to be HTTPS. If it's an HTTP server, the copy functionality would be disabled, regardless of the value of this flag. ##### Default value @@ -550,7 +578,7 @@ microstrategy.embeddingContexts.embedBotConsumptionPage({ ### `settings` -Specify the custom settings on the embedding pages. Including the non-UI settings of bot consumption page. +Specify the custom settings on the embedding pages. Including the non-UI settings of agent consumption page. #### Required? @@ -560,11 +588,11 @@ No ##### `botConsumption` -Use the `botConsumption` object to customize the options on the bot consumption page. The detailed properties contain: +Use the `botConsumption` object to customize the options on the agent consumption page. The detailed properties contain: - `disableManipulationsAutoSaving` - - Disable the bot instance manipulation auto saving or not. + - Disable the agent instance manipulation auto saving or not. - Default value: `false`. #### Sample diff --git a/docs/native-embedding-architecture/incremental-rendering.md b/docs/native-embedding-architecture/incremental-rendering.md new file mode 100644 index 0000000..9acaeaa --- /dev/null +++ b/docs/native-embedding-architecture/incremental-rendering.md @@ -0,0 +1,100 @@ +--- +title: Incremental Rendering +description: Use the Native Embedding SDK addWidgets API to render additional visualizations into an already-loaded dossier instance without re-rendering existing ones. +--- + + + +The `addWidgets` API allows you to render additional visualizations into an already-loaded dossier instance incrementally. This avoids re-rendering existing visualizations and enables lazy-loading patterns where visualizations are added on demand — for example, as the user scrolls or navigates within your application. + +## Example Case + +### Initial rendering with refresh() + +At the start, the user creates an environment, loads a dossier, and embeds one or more visualizations using the `refresh` API: + +```js +const mstrEnvironment = await microstrategy.embeddingComponent.environments.create({ + serverUrl: configs.serverUrl, + getAuthToken, +}); +const mstrDossier = await mstrEnvironment.loadDossier({ + projectId: configs.projectId, + objectId: configs.objectId, +}); +await mstrDossier.refresh([ + { + key: "K52", + container: document.getElementById("container1"), + }, +]); +``` + +### Add a visualization or a panel stack + +After the initial render, you can add another visualization or panel stack either from the same page or from a different page within the same chapter or another chapter. The existing visualization is not re-rendered: + +```js +await mstrDossier.addWidgets([ + { + key: "W66", + container: document.getElementById("container2"), + }, +]); +``` + +### Add multiple visualizations at once + +Multiple visualizations or panel stacks can be added in a single `addWidgets` call. They may come from different pages or chapters: + +```js +await mstrDossier.addWidgets([ + { + key: "W66", + container: document.getElementById("container2"), + }, + { + key: "W75", + container: document.getElementById("container3"), + }, +]); +``` + +## API + +### MstrDossier.addWidgets(widgetAndContainers) + +#### Function + +`async MstrDossier.addWidgets(widgetAndContainers)` + +#### Input Parameters + +| Parameter name | Data Type | Description | Default Value | Is Required | +| ------------------------------- | ----------- | --------------------------------------------------------------------- | ------------- | ----------- | +| widgetAndContainers | Array | An array of objects specifying visualizations or panle stacks to add. | N/A | true | +| widgetAndContainers[].key | string | The visualization or panel stack key to render. | N/A | true | +| widgetAndContainers[].container | HTMLElement | The DOM container element to render the viz into. | N/A | true | + +#### Response + +A Promise that resolves when all visualizations have been rendered. + +#### Prerequisites + +- The dossier must have been rendered with `refresh()` at least once before calling `addWidgets`. +- The container elements must already exist in the DOM and have a defined width and height. + +#### API Errors + +| Error case | Error handling | Error message | +| ----------------------------------------------------- | -------------------------------- | ------------------------------------------ | +| `addWidgets` called before `refresh` | The error object could be caught | The validation error | +| Invalid viz key (not found in the dossier definition) | The error object could be caught | The validation error | +| The background REST API fails | Caught by custom error handler | The error message provided by the REST API | + +## Notes + +- `addWidgets` does not re-render visualizations/panel stacks that were already rendered by `refresh()` or previous `addWidgets` calls. +- Visualizations/panel stacks from different pages and chapters can be added incrementally. The SDK fetches the necessary page data internally. +- Filters and manipulations applied after `addWidgets` will affect all rendered visualizations that are targeted by the filter/selector. diff --git a/docs/whats-new-in-the-embedding-sdk.md b/docs/whats-new-in-the-embedding-sdk.md index c404506..55d6400 100644 --- a/docs/whats-new-in-the-embedding-sdk.md +++ b/docs/whats-new-in-the-embedding-sdk.md @@ -5,6 +5,11 @@ description: In each release, changes are made to make the MicroStrategy SDK mor In each release, changes are made to make the MicroStrategy SDK more powerful and easier to use. +## Strategy ONE June 2026 + +- [Support native incremental rendering](./native-embedding-architecture/incremental-rendering) + - Use the new `MstrDossier.addWidgets()` API to enable incremental rendering on an existing `MstrDossier` instance. + ## Strategy ONE April 2026 - [New property `embeddingHostPortal`](./add-functionality/methods-and-properties.md#embeddinghostportal) diff --git a/sidebars.js b/sidebars.js index 5734217..9ea7339 100644 --- a/sidebars.js +++ b/sidebars.js @@ -95,8 +95,11 @@ const sidebars = { type: "doc", id: "embed-bot-consumption-page/embed-bot-consumption-page", }, - label: "Embed Strategy bot consumption page", - items: ["embed-bot-consumption-page/embed-bot-consumption-properties"], + label: "Embed Strategy agent consumption page", + items: [ + "embed-bot-consumption-page/embed-bot-consumption-properties", + "embed-bot-consumption-page/add-agent-event", + ], }, { type: "category", @@ -148,6 +151,7 @@ const sidebars = { "native-embedding-architecture/use-bookmark", "native-embedding-architecture/multiple-instances-for-one-dossier", "native-embedding-architecture/feature-flags", + "native-embedding-architecture/incremental-rendering", ], }, "samples",