diff --git a/docs/add-functionality/methods-and-properties.md b/docs/add-functionality/methods-and-properties.md index 7ea9207..d1249cc 100644 --- a/docs/add-functionality/methods-and-properties.md +++ b/docs/add-functionality/methods-and-properties.md @@ -73,6 +73,8 @@ The `url` property refers to the full URL of the dashboard to be embedded. There 1. Use `serverURL`, `configAppId`, `applicationID`, `objectID`, and `pageKey` properties. 1. If the `configAppId` property is not provided, embedding SDK will build the URL using: `serverURL` + '/app/' + `applicationID` + '/' + `objectID` + '/' + `pageKey`. 1. Otherwise the URL will be: `serverURL` + '/app/' + 'config/' + `configAppId` + '/' + `applicationID` + '/' + `objectID` + '/' + `pageKey`. +1. The `configAppId` refers to the application Id of the embeded dashboard. +1. The `applicationID` refers to the project Id of the embeded dashboard. #### Required? diff --git a/docs/embed-library-main-page/embed-library-properties.md b/docs/embed-library-main-page/embed-library-properties.md index 016722c..86b20ed 100644 --- a/docs/embed-library-main-page/embed-library-properties.md +++ b/docs/embed-library-main-page/embed-library-properties.md @@ -3,19 +3,24 @@ title: Properties for an embedded Library home page description: Describes the properties that can be set for an embedded Library home page. --- -When you embed a Library home page into a web page, you use the `embedLibraryPage(props)` method under the `microstrategy.embeddingContexts` namespace. +When you embed a Library home page into a web page, you use the `embedLibraryPage(props)` method +under the `microstrategy.embeddingContexts` namespace. ## Method ### `microstrategy.embeddingContexts.embedLibraryPage(props)` -This method creates an iFrame on the web page (in the location specified by the `placeholder` property) and inserts a link to the Library home 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 Library home page URL (specified by the `serverUrl` property). #### Return value This method returns a promise, which is resolved when the Library home page is loaded. -The `props` parameter contains required key:value pairs that defines the Library Server URL and the `
` placeholder where the iFrame containing the Library home 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 Library home 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: @@ -128,7 +133,8 @@ N/A ### `customAuthenticationType` -Specifies the token type returned by the `getLoginToken` function. There are two possible values, which can be provided by the CustomAuthenticationType enumeration. +Specifies the token type returned by the `getLoginToken` function. There are two possible values, +which can be provided by the CustomAuthenticationType enumeration. #### Required? @@ -144,7 +150,9 @@ N/A ### `getLoginToken` -Specifies a function that returns a promise, which is resolved with either authorization token (`authToken`) or the identity token (`identityToken`) The token type is specified by the customAuthenticationType property. +Specifies a function that returns a promise, which is resolved with either authorization token +(`authToken`) or the identity token (`identityToken`) The token type is specified by the +customAuthenticationType property. #### Required? @@ -156,9 +164,12 @@ See the sample code in the next column for the default implementation of this fu #### Sample -When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do this using an `XMLHttpRequest`, if your browser does not support `fetch`. +When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following +sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do +this using an `XMLHttpRequest`, if your browser does not support `fetch`. -The `getLoginToken` function can be found in [the `getLoginToken` doc](../add-functionality/methods-and-properties#getlogintoken) +The `getLoginToken` function can be found in +[the `getLoginToken` doc](../add-functionality/methods-and-properties#getlogintoken) ```js microstrategy.embeddingContexts.embedLibraryPage({ @@ -173,15 +184,20 @@ microstrategy.embeddingContexts.embedLibraryPage({ }); ``` -When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you need to add a component to your web server. Refer to Use Custom Authentication for more information. +When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you need to add +a component to your web server. Refer to Use Custom Authentication for more information. ### `disableCustomErrorHandlerOnCreate` To disable the custom error handler, set `disableCustomErrorHandlerOnCreate` to true. -If this flag is set, all the errors occur in the initial loading process and manual actions would be handled by OOTB Library itself, an error dialog would pop up. +If this flag is set, all the errors occur in the initial loading process and manual actions would be +handled by OOTB Library itself, an error dialog would pop up. -You could also refer to [Custom error handling during dashboard creation](../add-functionality/error-handling.md#custom-error-handling-during-dashboard-creation) to see the usage of this parameter in `microstrategy.dossier.create`, which has the same effect as in `microstrategy.embeddingContexts.embedLibraryPage` function. +You could also refer to +[Custom error handling during dashboard creation](../add-functionality/error-handling.md#custom-error-handling-during-dashboard-creation) +to see the usage of this parameter in `microstrategy.dossier.create`, which has the same effect as +in `microstrategy.embeddingContexts.embedLibraryPage` function. #### Required? @@ -203,9 +219,13 @@ microstrategy.embeddingContexts.embedLibraryPage({ ### `errorHandler` -The custom error handler that executes when the error occurs in the initial loading process. It's a callback function that contains one parameter, `error`. The error object has the property `message`, which contains the detailed error message. +The custom error handler that executes when the error occurs in the initial loading process. It's a +callback function that contains one parameter, `error`. The error object has the property `message`, +which contains the detailed error message. -Whether `errorHandler` is set, the error occured inside the library home page would output an error in the browser console. The detailed behavior could be seen in [The overall Library error behavior in embed case](../add-functionality/error-handling.md#the-overall-library-error-behavior-in-embed-case). +Whether `errorHandler` is set, the error occured inside the library home page would output an error +in the browser console. The detailed behavior could be seen in +[The overall Library error behavior in embed case](../add-functionality/error-handling.md#the-overall-library-error-behavior-in-embed-case). #### Required? @@ -230,12 +250,18 @@ microstrategy.embeddingContexts.embedLibraryPage({ ### `sessionErrorHandler` -The custom error handler that executes when an session expiration error occurs. It's a callback function that contains one parameter, `error`. The error object has the property `message`, which contains the detailed error message. +The custom error handler that executes when an session expiration error occurs. It's a callback +function that contains one parameter, `error`. The error object has the property `message`, which +contains the detailed error message. When session expires: -- If `sessionErrorHandler` is not set, the embedded page would redirect to the OOTB library login page. -- If `sessionErrorHandler` is set, the session error handler would be triggered and the embedded page would not change for 1 minute. If after 1 minute, the error handler doesn't do anything(like reauthentication and refresh page) to renew the session, the embedded page would redirect to the OOTB Library login page. +- If `sessionErrorHandler` is not set, the embedded page would redirect to the OOTB library login + page. +- If `sessionErrorHandler` is set, the session error handler would be triggered and the embedded + page would not change for 1 minute. If after 1 minute, the error handler doesn't do anything(like + reauthentication and refresh page) to renew the session, the embedded page would redirect to the + OOTB Library login page. #### Required? @@ -264,8 +290,10 @@ Specifies the application that the user wants to show in the embedded page. The application in Strategy has 2 categories: -- If the application selects library home page as its home screen, the library home page would be embedded with the application's configuration. -- If the application selects a dashboard as its home screen, the embedding would fail and an error would occur. +- If the application selects library home page as its home screen, the library home page would be + embedded with the application's configuration. +- If the application selects a dashboard as its home screen, the embedding would fail and an error + would occur. #### Required? @@ -281,15 +309,19 @@ N/A ### `customUi` -Specifies the custom UI settings on the embedded pages, including Library home page, dashboard consumption page，dashboard authoring page, and report consumption page. +Specifies the custom UI settings on the embedded pages, including Library home page, dashboard +consumption page，dashboard authoring page, and report consumption page. #### Properties -Please see all the properties in [The customized UI settings in Embedding SDK](./embed-custom-ui-on-all-pages.md) +Please see all the properties in +[The customized UI settings in Embedding SDK](./embed-custom-ui-on-all-pages.md) #### The navigation bar custom setting behavior -The property `customUi.library.navigationBar.enabled` would affect the library home page UI together with the navigation bar setting in the application settings. There are 2 related item in the application settings in Workstation: +The property `customUi.library.navigationBar.enabled` would affect the library home page UI together +with the navigation bar setting in the application settings. There are 2 related item in the +application settings in Workstation: - Disable toolbar - Collapse toolbar by default @@ -298,32 +330,44 @@ The property `customUi.library.navigationBar.enabled` would affect the library h The detailed embedding behavior is as below: -- If `customUi.library.navigationBar.enabled` is false, the navigation bar is disabled by the Embedding SDK settings, and it would never be shown on the embedded library page. +- If `customUi.library.navigationBar.enabled` is false, the navigation bar is disabled by the + Embedding SDK settings, and it would never be shown on the embedded library page. -- If `customUi.library.navigationBar.enabled` is true, the setting would still be combined with the settings in the application, to determine the final visibility of the navigation bar: +- If `customUi.library.navigationBar.enabled` is true, the setting would still be combined with the + settings in the application, to determine the final visibility of the navigation bar: - If the current application disables the navigation bar, the navigation bar would never be shown. - If the current application enables the navigation bar: - - If you choose "Collapse toolbar by default" in application settings, the navigation bar is collapsible: + - If you choose "Collapse toolbar by default" in application settings, the navigation bar is + collapsible: - - If `customUi.library.sidebar.show` is false or not set, on the embedded library page, the navigation bar would be collapsed at the start, and only would be expanded/visible when the user expands it manually. + - If `customUi.library.sidebar.show` is false or not set, on the embedded library page, the + navigation bar would be collapsed at the start, and only would be expanded/visible when the + user expands it manually. - - If `customUi.library.sidebar.show` is true, as on the OOTB library page, the sidebar couldn’t be expand unless the navigation bar is visible, the navigation bar would be expanded and shown in this case. + - If `customUi.library.sidebar.show` is true, as on the OOTB library page, the sidebar + couldn’t be expand unless the navigation bar is visible, the navigation bar would be + expanded and shown in this case. - - If you don't choose "Collapse toolbar by default", the navigation bar would be shown on the embedded library page. + - If you don't choose "Collapse toolbar by default", the navigation bar would be shown on the + embedded library page. #### The sidebar custom setting behavior -`customUi.library.navigationBar.enabled` would also affect the library home page UI together with the sidebar setting in the application settings: +`customUi.library.navigationBar.enabled` would also affect the library home page UI together with +the sidebar setting in the application settings: ![Application sidebar settings](../images/custom-app-sidebar-setting.png) The special behaviors are as below: -- If sidebar is disabled in the application settings, whether setting `customUi.library.sidebar.show` to true or false, the sidebar couldn't be shown. -- If the navigation bar is enabled in `customUi.library.navigationBar.enabled` and application settings, and "Collapse toolbar by default" is enabled by default, when `customUi.library.sidebar.show` is true, the navigation bar would be expanded and shown. +- If sidebar is disabled in the application settings, whether setting + `customUi.library.sidebar.show` to true or false, the sidebar couldn't be shown. +- If the navigation bar is enabled in `customUi.library.navigationBar.enabled` and application + settings, and "Collapse toolbar by default" is enabled by default, when + `customUi.library.sidebar.show` is true, the navigation bar would be expanded and shown. ### `libraryItemSelectMode` @@ -368,11 +412,17 @@ Specifies the page on the sidebar entries that you want to embed. }; ``` -- `currentPage.key`: This field specifies the key of the page that the user wants to embed. Its available values are the menu items in the sidebar, which could be in ['home', 'insights', 'subscriptions', 'defaultGroups', 'myGroups', 'contentDiscovery']. +- `currentPage.key`: This field specifies the key of the page that the user wants to embed. Its + available values are the menu items in the sidebar, which could be in ['home', 'insights', + 'subscriptions', 'defaultGroups', 'myGroups', 'contentDiscovery']. -- `currentPage.targetGroup`: This field is only necessary when `currentPage.key` is 'defaultGroups' or 'myGroups', as on library home page the user can't select these 2 menu items but only could select the group items under them. It specifies which group item the user wants to select. +- `currentPage.targetGroup`: This field is only necessary when `currentPage.key` is 'defaultGroups' + or 'myGroups', as on library home page the user can't select these 2 menu items but only could + select the group items under them. It specifies which group item the user wants to select. -- `currentPage.targetGroup.id`: The id of the group the user wants to select. Its available values could be got from the API `EmbeddingContext.libraryPage.getAllMyGroups()` or `EmbeddingContext.libraryPage.getAllDefaultGroups()`. +- `currentPage.targetGroup.id`: The id of the group the user wants to select. Its available values + could be got from the API `EmbeddingContext.libraryPage.getAllMyGroups()` or + `EmbeddingContext.libraryPage.getAllDefaultGroups()`. - `currentPage.targetGroup.name`: The name of the group the user wants to select. @@ -380,7 +430,9 @@ Specifies the page on the sidebar entries that you want to embed. - `currentPage`: Not required - `currentPage.key`: Required if `currentPage` is provided -- `currentPage.targetGroup.id` and `currentPage.targetGroup.name`: The user must at least provide one of them. When both of them are provided, `currentPage.targetGroup.id` would have higher priority. +- `currentPage.targetGroup.id` and `currentPage.targetGroup.name`: The user must at least provide + one of them. When both of them are provided, `currentPage.targetGroup.id` would have higher + priority. #### Default value @@ -401,3 +453,42 @@ microstrategy.embeddingContexts.embedLibraryPage({ }, }); ``` + +### `settings` + +Configure global settings for the embedded library page. + +`settings` format: + +```javascript +{ + filter: { + projects: ["B7CA92F04B9FAE8D941C3E9B7E0CD754"]; + } +} +``` + +- `settings.filter.projects`: This field allows you to filter the library to display content from a + specific project. Currently, only one project can be specified at a time. + +#### Required? + +- `settings.filter.projects`: Not required + +#### Default value + +N/A + +#### Sample + +```js +microstrategy.embeddingContexts.embedLibraryPage({ + serverUrl: url, + placeholder: container, + settings: { + filter: { + projects: ["B7CA92F04B9FAE8D941C3E9B7E0CD754"], + }, + }, +}); +``` diff --git a/docs/embed-report-page/embed-report-properties.md b/docs/embed-report-page/embed-report-properties.md index f3535cb..18663ba 100644 --- a/docs/embed-report-page/embed-report-properties.md +++ b/docs/embed-report-page/embed-report-properties.md @@ -327,3 +327,36 @@ The detailed embedding behavior is below: - If you choose "Collapse toolbar by default" in the application settings, the navigation bar is collapsed at the start and is only expanded/visible when the user expands it manually. - If you don't choose "Collapse toolbar by default", the navigation bar is shown on the embedded report page. + +### `settings` + +#### Required? + +No + +#### Properties + +##### `reportConsumption` + +Use the `reportConsumption` object to customize the options on the report consumption page. The detailed properties contain: + +- `disableManipulationsAutoSaving` + + - Disable the report instance manipulation auto saving or not. + - Default value: `false`. + +### `instance` + +Use this `instance` object to specify a report based dashboard instance for the embedded report. If you would like to make some manipulation to the report based dashboard instance before it is embedded, you can use this property, e.g., sorting a column. If the `instance` is used, the Embedding SDK will use it instead of creating a new report based dashboard instance. + +#### Required? + +No + +#### Properties + +- `mid` - This instance ID. + +#### Default value + +`null` diff --git a/docs/images/information-window-limitations.png b/docs/images/information-window-limitations.png new file mode 100644 index 0000000..c8b3bbd Binary files /dev/null and b/docs/images/information-window-limitations.png differ diff --git a/docs/images/information-window-size.png b/docs/images/information-window-size.png new file mode 100644 index 0000000..9771480 Binary files /dev/null and b/docs/images/information-window-size.png differ diff --git a/docs/native-embedding-architecture/apply-filter.md b/docs/native-embedding-architecture/apply-filter.md index 0f66a90..c296d5f 100644 --- a/docs/native-embedding-architecture/apply-filter.md +++ b/docs/native-embedding-architecture/apply-filter.md @@ -274,7 +274,9 @@ Here are some examples for the filter object in the `MstrDossier.applyFilter()` #### On-Page selectors -To apply selections to on-page selectors, use the same input as chapter-level filters. +##### Attribute Element Filter + +To apply selections on Attribute Element filter inside a page, use the same input as chapter-level filters. - Select the element list of the selector @@ -326,6 +328,45 @@ To apply selections to on-page selectors, use the same input as chapter-level fi } ``` +##### Attribute/Metric Selector + +To apply selections on an Attribute/Metric selector inside a page, you can use the following input: + +- Select the object list of the selector + + ```js + try { + await mstrDossier.applyFilter({ + key: "W76", + currentSelection: { + objectItems: [ + { + id: "", + name: "", + }, + ], + }, + }); + } catch (error) { + // Your own error handling code + } + ``` + +- Unset the selection of the selector + + ```js + try { + await mstrDossier.applyFilter({ + key: "W76", + currentSelection: { + selectionStatus: "unfiltered", + }, + }); + } catch (error) { + // Your own error handling code + } + ``` + #### Visualizations used as filters - Select attribute elements of the visualization diff --git a/docs/native-embedding-architecture/information-window.md b/docs/native-embedding-architecture/information-window.md new file mode 100644 index 0000000..ca4f80d --- /dev/null +++ b/docs/native-embedding-architecture/information-window.md @@ -0,0 +1,34 @@ +--- +title: Information Window +description: Interactive contextual information display for visualizations +--- + + + +## Overview + +The Information Window feature enhances data visualization interactivity by providing contextual details in a dynamic overlay. When a user clicks on a visualization element, a contextual window appears displaying additional information that is automatically filtered based on the selected element. + +## Implementation + +To implement the Information Window feature, please refer to the [MstrDossier API documentation](mstr-dossier.md) for the required parameters and implementation details. + +## Behavior Specifications + +### Size Management + +The Information Window automatically adjusts its dimensions based on the content and maintains the optimal width-to-height ratio consistent with MicroStrategyLibrary standards: + +![Information Window Size Adaptation](../images/information-window-size.png) + +### Positioning Logic + +The Information Window intelligently positions itself relative to the interaction point. When a user clicks on a visualization element, the window appears proximal to the click location while ensuring it remains fully visible within the viewport. + +## Technical Limitations + +The Information Window feature has specific compatibility constraints: + +![Information Window Compatibility Constraints](../images/information-window-limitations.png) + +Certain selector components and filtering mechanisms are not compatible with the Information Window rendering system. For optimal implementation, avoid using these unsupported configurations. diff --git a/docs/native-embedding-architecture/mstr-dossier.md b/docs/native-embedding-architecture/mstr-dossier.md index fe338d3..55a7b9b 100644 --- a/docs/native-embedding-architecture/mstr-dossier.md +++ b/docs/native-embedding-architecture/mstr-dossier.md @@ -17,13 +17,15 @@ The object returned from the `MstrEnvironment.loadDossier()` function, which all #### Input Parameters -| Parameter Name | Data Type | Description | Is Required | -| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | -| props | Array | This parameter cannot be empty. It describes the visualizations that must appear on the page. Each visualization must have a valid container. If you call `refresh()` for a second time, the visualizations rendered in the former `refresh()` call are destroyed first, then all the visualizations specified in the second `refresh()` call are shown on page by page. | true | -| props[i].key | String | The visualization key id. | true | -| props[i].container | HTMLElement | The HTML element used for displaying the visualization. The HTML element must be in the current DOM tree of the client’s page. All elements must exist and cannot be in iframes. The `Node.contains()` function is used to determine this and is compatible with all browsers. | true | -| options | Object | An object containing optional parameters to control the behavior of the `refresh()` function. | false | -| options.signal | AbortSignal | An `AbortSignal` object that allows you to abort the refresh operation. This signal is typically created by an `AbortController` and can be used to cancel the operation by calling `AbortController.abort()` if needed. | false | +| Parameter Name | Data Type | Description | Is Required | +| -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | +| props | Array | This parameter cannot be empty. It describes the visualizations that must appear on the page. Each visualization must have a valid container. If you call `refresh()` for a second time, the visualizations rendered in the former `refresh()` call are destroyed first, then all the visualizations specified in the second `refresh()` call are shown on page by page. | true | +| props[i].key | String | The visualization key id. | true | +| props[i].container | HTMLElement | The HTML element used for displaying the visualization. The HTML element must be in the current DOM tree of the client's page. All elements must exist and cannot be in iframes. The `Node.contains()` function is used to determine this and is compatible with all browsers. | true | +| props[i].infoWindow | Object | An object that controls the information window behavior for the visualization. | false | +| props[i].infoWindow.enable | Boolean | When set to `true`, enables the information window rendering for the visualization. | false | +| options | Object | An object containing optional parameters to control the behavior of the `refresh()` function. | false | +| options.signal | AbortSignal | An `AbortSignal` object that allows you to abort the refresh operation. This signal is typically created by an `AbortController` and can be used to cancel the operation by calling `AbortController.abort()` if needed. | false | #### Response @@ -94,6 +96,37 @@ if (shouldAbortRefresh) { } ``` +With InfoWindow: + +```js +try { + const environment = await microstrategy.embeddingComponent.environments.create({ + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + getAuthToken: () => { + // Logic similar to the existing Native Embedding SDK. + }, + }); + const dossier = await environment.loadDossier({ + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", + }); + // Begin here + const containerHtmlElement = document.getElementById("containerA"); + await dossier.refresh([ + { + key: "K66", + container: containerHtmlElement, + infoWindow: { + enable: true, + }, + }, + ]); + // Your own code after the visualizations are all loaded +} catch (error) { + // Add your own handling logic here +} +``` + #### API Errors | Error Case | Error Category | Handling Module | Error Handling | @@ -107,6 +140,7 @@ if (shouldAbortRefresh) { | A container is occupied by other dossiers | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | | Other REST API errors | Other | Native Embedding SDK | Caught by the `catch()` of the promise object | | The key is the visualization key of the visualization in the panel | Invalid input | Native Embedding SDK | console err message in console "The visualization `${VisualizationKey}` is a visualization in a panel, which isn't supported." | +| Info window is not found for the specified visualization key | Invalid input | Native Embedding SDK | Console error message: `Info window is not found for visualization key:${vizKey}.` | | Object you pass to AbortController.abort(), or `AbortError: signal is aborted without reason` otherwise. | Abort Error | Native Embedding SDK | Caught by the `catch()` of the promise object | ### The get information API diff --git a/docs/support-for-different-authentication-environments/oauth2-apis.md b/docs/support-for-different-authentication-environments/oauth2-apis.md new file mode 100644 index 0000000..e254946 --- /dev/null +++ b/docs/support-for-different-authentication-environments/oauth2-apis.md @@ -0,0 +1,140 @@ +--- +title: Library OAuth2 authentication APIs +description: Describes the Embedding SDK APIs that is available for Library OAuth2 authentication. +--- + +To simplify the [Library OAuth2](https://doc-dev.microstrategy.com/producthelp/2021/Workstation/en-us/Content/oauth2.htm) login workflow, we expose new APIs + +`microstrategy.auth.oauthLogin(serverUrl, options)` + +`microstrategy.auth.oauthRefreshToken(serverUrl, options)` + +The details of those new APIs are as below: + +### `microstrategy.auth.oauthLogin(serverUrl, options)` + +#### Description + +This API can be used to start the Library OAuth2 login workflow on the embedding scenario. + +#### Input Parameters + +- `serverUrl` (`string`): + The URL of a Library server that has been successfully configured with OAuth2. + +- `options` (`OAuth2LoginOptions`): + An object containing the following fields: + + - `clientId` (`string`): + The client identifier issued by the authorization server during OAuth2 client registration. + - `clientSecret` (`string`, optional): + The client secret corresponding to the clientId, used to authenticate the client with the authorization server. + + If provided together with `requireRefreshToken: true`, a refresh token will be issued as part of the login response. + + - `requireRefreshToken` (`boolean`, optional): + Specifies whether a refresh token should be requested during login. + + Only takes effect if `clientSecret` is provided. + + If true, both an access token and a refresh token will be returned. + + If false (or omitted), only an access token will be returned. + +#### Return type + +Returns a `Promise` that resolves to an object containing the following fields: + +```ts +{ + accessToken: string; + refreshToken?: string; +} +``` + +- accessToken: The OAuth2 access token for authenticating subsequent requests. +- refreshToken (optional): The refresh token that can be used to obtain a new access token when the + current one expires. + +#### Example + +```js +microstrategy.embeddingContexts.embedLibraryPage({ + serverUrl: "{YOUR_LIBRARY_SERVER_URL}", + placeholder: document.getElementById("LibraryHomePageContainer"), + enableCustomAuthentication: true, + customAuthenticationType: microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN, + getLoginToken: async () => { + const data = await microstrategy.auth.oauthLogin("{YOUR_LIBRARY_SERVER_URL}", { + clientId: "{YOUR_OAUTH2_CLIENT_ID}", + clientSecret: "{YOUR_OAUTH2_CLIENT_SECRET}", + requireRefreshToken: true, + }); + return data.accessToken; + }, +}); +``` + +### `microstrategy.auth.oauthRefreshToken(serverUrl, options)` + +#### Description + +This API allows obtaining a new access token using a previously acquired refresh token. + +#### Input Parameters + +- `serverUrl` (`string`): + The URL of a Library server that has been successfully configured with OAuth2. + +- `options` (`OAuth2RefreshTokenOptions`): + An object containing the following fields: + + - `clientId` (`string`): + The client identifier issued by the authorization server during OAuth2 client registration. + + - `clientSecret` (`string`): + The client secret corresponding to the clientId, used to authenticate the client with the authorization server. + + - `refreshToken` (`string`): + The refresh token that was previously obtained during login. + +#### Return type + +Returns a `Promise` that resolves to an object containing the following fields: + +```ts +{ + accessToken: string; + refreshToken: string; +} +``` + +- accessToken: The OAuth2 access token for authenticating subsequent requests. +- refreshToken: The refresh token that can be used to obtain a new access token when the + current one expires. + +#### Example + +```js +const data = await microstrategy.auth.oauthRefreshToken("{YOUR_LIBRARY_SERVER_URL}", { + clientId: "{YOUR_OAUTH2_CLIENT_ID}", + clientSecret: "{YOUR_OAUTH2_CLIENT_SECRET}", + refreshToken: "{YOUR_REFRESH_TOKEN}", +}); +const { accessToken } = data; +const { refreshToken } = data; +``` + +#### API errors + +This API would have the wrong behavior or report an error in the cases below: + +- When `serverUrl` is not a Library server that supports OAuth2 login. +- If you receive a `HTTP Status 400 - Bad Request` response, ensure that the redirectUrl is [correctly configured](https://doc-dev.microstrategy.com/producthelp/2021/Workstation/en-us/Content/config_oauth2.htm). The expected format for the redirectUrl is: `YOUR_LIBRARY_SERVER_URL/static/embedding/auth-end.html?origin=YOUR_EMBEDDING_ORIGIN` and Make sure to replace: + + - `YOUR_LIBRARY_SERVER_URL` with the actual Library server URL. + - `YOUR_EMBEDDING_ORIGIN` with the origin of the embedding application. For example, if your embedding page URL is `https://example.com:8443/path/demo.html`, then the origin is `https://example.com:8443`. + +- When the client application can't get the Strategy login window because of + [COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) + setting is too strict. diff --git a/docs/whats-new-in-the-embedding-sdk.md b/docs/whats-new-in-the-embedding-sdk.md index 90f7cce..e6ca828 100644 --- a/docs/whats-new-in-the-embedding-sdk.md +++ b/docs/whats-new-in-the-embedding-sdk.md @@ -5,7 +5,19 @@ 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. -## MicroStrategy ONE March 2025 +## Strategy ONE June 2025 + +- [Information Window](./native-embedding-architecture/information-window.md) + - Introduce the Information Window feature in Native Embedding SDK to enhance data visualization interactivity by providing contextual details in a dynamic overlay. +- [Retrieve and apply filters](./native-embedding-architecture/apply-filter#attributemetric-selector) + - Support the Attribute/Metric selector in `MstrDossier.applyFilter()` and `MstrDossier.applyFilters()` in Native Embedding SDK. + +## Strategy ONE April 2025 + +- [Properties for an embedded Library home page.](./embed-library-main-page/embed-library-properties.md#settings) + - Introduce `settings.filter.projects` to filter the library to display content from a specific project. + +## Strategy ONE March 2025 - [Embed MicroStrategy document consumption page.](./embed-document-consumption-page/embed-document-consumption-page.md) - Provide API to embed a document consumption page. diff --git a/sidebars.js b/sidebars.js index 6540a1c..1014782 100644 --- a/sidebars.js +++ b/sidebars.js @@ -36,6 +36,7 @@ const sidebars = { "support-for-different-authentication-environments/authentication-saml", "support-for-different-authentication-environments/new-authentication-apis", "support-for-different-authentication-environments/seamless-login", + "support-for-different-authentication-environments/oauth2-apis", ], }, { @@ -140,6 +141,7 @@ const sidebars = { "native-embedding-architecture/dossier-info-api", "native-embedding-architecture/apply-filter", "native-embedding-architecture/event-handling", + "native-embedding-architecture/information-window", ], }, "samples",