Skip to content

Commit a4670ad

Browse files
author
zhe
committed
Update
1 parent bb3791d commit a4670ad

File tree

10 files changed

+387
-41
lines changed

10 files changed

+387
-41
lines changed

‎docs/add-functionality/methods-and-properties.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,8 @@ The `url` property refers to the full URL of the dashboard to be embedded. There
7373
1. Use `serverURL`, `configAppId`, `applicationID`, `objectID`, and `pageKey` properties.
7474
1. If the `configAppId` property is not provided, embedding SDK will build the URL using: `serverURL` + '/app/' + `applicationID` + '/' + `objectID` + '/' + `pageKey`.
7575
1. Otherwise the URL will be: `serverURL` + '/app/' + 'config/' + `configAppId` + '/' + `applicationID` + '/' + `objectID` + '/' + `pageKey`.
76+
1. The `configAppId` refers to the application Id of the embeded dashboard.
77+
1. The `applicationID` refers to the project Id of the embeded dashboard.
7678

7779
#### Required?
7880

‎docs/embed-library-main-page/embed-library-properties.md‎

Lines changed: 124 additions & 33 deletions
Large diffs are not rendered by default.

‎docs/embed-report-page/embed-report-properties.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -327,3 +327,36 @@ The detailed embedding behavior is below:
327327
- 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.
328328

329329
- If you don't choose "Collapse toolbar by default", the navigation bar is shown on the embedded report page.
330+
331+
### `settings`
332+
333+
#### Required?
334+
335+
No
336+
337+
#### Properties
338+
339+
##### `reportConsumption`
340+
341+
Use the `reportConsumption` object to customize the options on the report consumption page. The detailed properties contain:
342+
343+
- `disableManipulationsAutoSaving`
344+
345+
- Disable the report instance manipulation auto saving or not.
346+
- Default value: `false`.
347+
348+
### `instance`
349+
350+
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.
351+
352+
#### Required?
353+
354+
No
355+
356+
#### Properties
357+
358+
- `mid` - This instance ID.
359+
360+
#### Default value
361+
362+
`null`

‎docs/images/information-window-limitations.png‎

31.4 KB
Loading

‎docs/images/information-window-size.png‎

11.6 KB
Loading

‎docs/native-embedding-architecture/information-window.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Information Window
3+
description: Interactive contextual information display for visualizations
4+
---
5+
6+
<Available since="StrategyJune 2025"/>
7+
8+
## Overview
9+
10+
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.
11+
12+
## Implementation
13+
14+
To implement the Information Window feature, please refer to the [MstrDossier API documentation](mstr-dossier.md) for the required parameters and implementation details.
15+
16+
## Behavior Specifications
17+
18+
### Size Management
19+
20+
The Information Window automatically adjusts its dimensions based on the content and maintains the optimal width-to-height ratio consistent with MicroStrategyLibrary standards:
21+
22+
![Information Window Size Adaptation](../images/information-window-size.png)
23+
24+
### Positioning Logic
25+
26+
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.
27+
28+
## Technical Limitations
29+
30+
The Information Window feature has specific compatibility constraints:
31+
32+
![Information Window Compatibility Constraints](../images/information-window-limitations.png)
33+
34+
Certain selector components and filtering mechanisms are not compatible with the Information Window rendering system. For optimal implementation, avoid using these unsupported configurations.

‎docs/native-embedding-architecture/mstr-dossier.md‎

Lines changed: 41 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,15 @@ The object returned from the `MstrEnvironment.loadDossier()` function, which all
1717

1818
#### Input Parameters
1919

20-
| Parameter Name | Data Type | Description | Is Required |
21-
| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
22-
| 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 |
23-
| props[i].key | String | The visualization key id. | true |
24-
| 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 |
25-
| options | Object | An object containing optional parameters to control the behavior of the `refresh()` function. | false |
26-
| 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 |
20+
| Parameter Name | Data Type | Description | Is Required |
21+
| -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
22+
| 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 |
23+
| props[i].key | String | The visualization key id. | true |
24+
| 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 |
25+
| props[i].infoWindow | Object | An object that controls the information window behavior for the visualization. | false |
26+
| props[i].infoWindow.enable | Boolean | When set to `true`, enables the information window rendering for the visualization. | false |
27+
| options | Object | An object containing optional parameters to control the behavior of the `refresh()` function. | false |
28+
| 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 |
2729

2830
#### Response
2931

@@ -94,6 +96,37 @@ if (shouldAbortRefresh) {
9496
}
9597
```
9698

99+
With InfoWindow:
100+
101+
```js
102+
try {
103+
const environment = await microstrategy.embeddingComponent.environments.create({
104+
serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary",
105+
getAuthToken: () => {
106+
// Logic similar to the existing Native Embedding SDK.
107+
},
108+
});
109+
const dossier = await environment.loadDossier({
110+
projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F",
111+
objectId: "D9AB379D11EC92C1D9DC0080EFD415BB",
112+
});
113+
// Begin here
114+
const containerHtmlElement = document.getElementById("containerA");
115+
await dossier.refresh([
116+
{
117+
key: "K66",
118+
container: containerHtmlElement,
119+
infoWindow: {
120+
enable: true,
121+
},
122+
},
123+
]);
124+
// Your own code after the visualizations are all loaded
125+
} catch (error) {
126+
// Add your own handling logic here
127+
}
128+
```
129+
97130
#### API Errors
98131

99132
| Error Case | Error Category | Handling Module | Error Handling |
@@ -107,6 +140,7 @@ if (shouldAbortRefresh) {
107140
| A container is occupied by other dossiers | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object |
108141
| Other REST API errors | Other | Native Embedding SDK | Caught by the `catch()` of the promise object |
109142
| 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." |
143+
| 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}.` |
110144
| 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 |
111145

112146
### The get information API

‎docs/support-for-different-authentication-environments/oauth2-apis.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: Library OAuth2 authentication APIs
3+
description: Describes the Embedding SDK APIs that is available for Library OAuth2 authentication.
4+
---
5+
6+
To simplify the [Library OAuth2](https://doc-dev.microstrategy.com/producthelp/2021/Workstation/en-us/Content/oauth2.htm) login workflow, we expose new APIs
7+
8+
`microstrategy.auth.oauthLogin(serverUrl, options)`
9+
10+
`microstrategy.auth.oauthRefreshToken(serverUrl, options)`
11+
12+
The details of those new APIs are as below:
13+
14+
### `microstrategy.auth.oauthLogin(serverUrl, options)`
15+
16+
#### Description
17+
18+
This API can be used to start the Library OAuth2 login workflow on the embedding scenario.
19+
20+
#### Input Parameters
21+
22+
- `serverUrl` (`string`):
23+
The URL of a Library server that has been successfully configured with OAuth2.
24+
25+
- `options` (`OAuth2LoginOptions`):
26+
An object containing the following fields:
27+
28+
- `clientId` (`string`):
29+
The client identifier issued by the authorization server during OAuth2 client registration.
30+
- `clientSecret` (`string`, optional):
31+
The client secret corresponding to the clientId, used to authenticate the client with the authorization server.
32+
33+
If provided together with `requireRefreshToken: true`, a refresh token will be issued as part of the login response.
34+
35+
- `requireRefreshToken` (`boolean`, optional):
36+
Specifies whether a refresh token should be requested during login.
37+
38+
Only takes effect if `clientSecret` is provided.
39+
40+
If true, both an access token and a refresh token will be returned.
41+
42+
If false (or omitted), only an access token will be returned.
43+
44+
#### Return type
45+
46+
Returns a `Promise` that resolves to an object containing the following fields:
47+
48+
```ts
49+
{
50+
accessToken: string;
51+
refreshToken?: string;
52+
}
53+
```
54+
55+
- accessToken: The OAuth2 access token for authenticating subsequent requests.
56+
- refreshToken (optional): The refresh token that can be used to obtain a new access token when the
57+
current one expires.
58+
59+
#### Example
60+
61+
```js
62+
microstrategy.embeddingContexts.embedLibraryPage({
63+
serverUrl: "{YOUR_LIBRARY_SERVER_URL}",
64+
placeholder: document.getElementById("LibraryHomePageContainer"),
65+
enableCustomAuthentication: true,
66+
customAuthenticationType: microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN,
67+
getLoginToken: async () => {
68+
const data = await microstrategy.auth.oauthLogin("{YOUR_LIBRARY_SERVER_URL}", {
69+
clientId: "{YOUR_OAUTH2_CLIENT_ID}",
70+
clientSecret: "{YOUR_OAUTH2_CLIENT_SECRET}",
71+
requireRefreshToken: true,
72+
});
73+
return data.accessToken;
74+
},
75+
});
76+
```
77+
78+
### `microstrategy.auth.oauthRefreshToken(serverUrl, options)`
79+
80+
#### Description
81+
82+
This API allows obtaining a new access token using a previously acquired refresh token.
83+
84+
#### Input Parameters
85+
86+
- `serverUrl` (`string`):
87+
The URL of a Library server that has been successfully configured with OAuth2.
88+
89+
- `options` (`OAuth2RefreshTokenOptions`):
90+
An object containing the following fields:
91+
92+
- `clientId` (`string`):
93+
The client identifier issued by the authorization server during OAuth2 client registration.
94+
95+
- `clientSecret` (`string`):
96+
The client secret corresponding to the clientId, used to authenticate the client with the authorization server.
97+
98+
- `refreshToken` (`string`):
99+
The refresh token that was previously obtained during login.
100+
101+
#### Return type
102+
103+
Returns a `Promise` that resolves to an object containing the following fields:
104+
105+
```ts
106+
{
107+
accessToken: string;
108+
refreshToken: string;
109+
}
110+
```
111+
112+
- accessToken: The OAuth2 access token for authenticating subsequent requests.
113+
- refreshToken: The refresh token that can be used to obtain a new access token when the
114+
current one expires.
115+
116+
#### Example
117+
118+
```js
119+
const data = await microstrategy.auth.oauthRefreshToken("{YOUR_LIBRARY_SERVER_URL}", {
120+
clientId: "{YOUR_OAUTH2_CLIENT_ID}",
121+
clientSecret: "{YOUR_OAUTH2_CLIENT_SECRET}",
122+
refreshToken: "{YOUR_REFRESH_TOKEN}",
123+
});
124+
const { accessToken } = data;
125+
const { refreshToken } = data;
126+
```
127+
128+
#### API errors
129+
130+
This API would have the wrong behavior or report an error in the cases below:
131+
132+
- When `serverUrl` is not a Library server that supports OAuth2 login.
133+
- 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:
134+
135+
- `YOUR_LIBRARY_SERVER_URL` with the actual Library server URL.
136+
- `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`.
137+
138+
- When the client application can't get the Strategy login window because of
139+
[COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy)
140+
setting is too strict.

‎docs/whats-new-in-the-embedding-sdk.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,17 @@ description: In each release, changes are made to make the MicroStrategy SDK mor
55

66
In each release, changes are made to make the MicroStrategy SDK more powerful and easier to use.
77

8-
## MicroStrategy ONE March 2025
8+
## Strategy ONE June 2025
9+
10+
- [Information Window](./native-embedding-architecture/information-window.md)
11+
- Introduce the Information Window feature to enhance data visualization interactivity by providing contextual details in a dynamic overlay.
12+
13+
## Strategy ONE April 2025
14+
15+
- [Properties for an embedded Library home page.](./embed-library-main-page/embed-library-properties.md#settings)
16+
- Introduce `settings.filter.projects` to filter the library to display content from a specific project.
17+
18+
## Strategy ONE March 2025
919

1020
- [Embed MicroStrategy document consumption page.](./embed-document-consumption-page/embed-document-consumption-page.md)
1121
- Provide API to embed a document consumption page.

‎sidebars.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ const sidebars = {
3636
"support-for-different-authentication-environments/authentication-saml",
3737
"support-for-different-authentication-environments/new-authentication-apis",
3838
"support-for-different-authentication-environments/seamless-login",
39+
"support-for-different-authentication-environments/oauth2-apis",
3940
],
4041
},
4142
{
@@ -140,6 +141,7 @@ const sidebars = {
140141
"native-embedding-architecture/dossier-info-api",
141142
"native-embedding-architecture/apply-filter",
142143
"native-embedding-architecture/event-handling",
144+
"native-embedding-architecture/information-window",
143145
],
144146
},
145147
"samples",

0 commit comments

Comments
 (0)