Use phased embedding
The Power BI embedded analytics powerbi.load and report.render APIs can improve end-user experience by giving developers more flexibility to phase report embedding.
Normally, you load an embedded report by using powerbi.embed:
let report = powerbi.embed(embedContainer, embedConfig);
The embedded report loads and renders in the user interface. The end user then sees any interactions with the rendered report. For example, if you apply a slicer state, the end user sees the slicer take effect after the report renders.
To hide these interactions from end users, the powerbi.load and report.render APIs break down the embedding process into phases. The powerbi.load function loads the report so you can interact with items before end users see the results. The report.render function then displays the report.
Load
The powerbi.load function loads the report but doesn't render it, so interactions can happen before the end user sees the results. For example, you can use powerbi.load with report.getPages, and then specify which page to show the end user. Or, you can use page.getVisuals, and then decide which visuals to show or hide.
Like powerbi.embed, the powerbi.load function requires an HTML element and an IEmbedConfiguration object.
When the load finishes, a loaded event fires.
let config = {
...
};
// Get a reference to the embedded report HTML element.
let embedContainer = $('#embedContainer')[0];
// Load the report in the container.
let report = powerbi.load(embedContainer, config);
report.on('loaded', function() {
...
});
Render
If you use powerbi.load, you must then call the report.render function on the loaded event handler function, after running your code. Use report.render to continue the report rendering and display the embedded report.
A rendered event fires when the report finishes rendering.
report.on('loaded', function() {
report.render();
});
report.on('rendered', () => {
...
});
For more information about handling events, see How to handle events.
Example
The following code example loads a report, sets filters, and then renders the filtered report.
// Build the config object.
let config = {
type: 'report',
tokenType: TokenType.Embed,
accessToken: ...,
embedUrl: ...,
id: ...,
...
};
// Get a reference to the embedded report HTML element.
let embedContainer = $('#embedContainer')[0];
// Load the report in the container.
let report = powerbi.load(embedContainer, config);
...
report.on('loaded', async () => {
await report.setFilters(filters);
report.render();
});
Limitations
Phased embedding can slow down report rendering, so be sure to use it correctly and only when you need it.
You can call the following APIs after you load the report and before you call report.render:
| Method | Action |
|---|---|
| BookmarksManager.getBookmarks, BookmarksManager.apply | Get and apply bookmarks. Capturing bookmarks isn't supported. |
| Report.updateSettings | Update report settings. |
| Report.applyTheme | Apply the report theme. |
| Report.getFilters, Report.setFilters, Report.removeFilters | Get, set, and remove report filters. |
| Report.getPages | Get the report pages. |
| Page.setActive | Set the active report page. |
| Page.getFilters, Page.setFilters, Page.removeFilters | Get, set, and remove page filters. |
| Page.getVisuals | Get page visuals. |
| Visual.getFilters, Visual.setFilters, Visual.removeFilters | Get, set, and remove visual filters. |
| Visual.getSlicerState, Visual.setSlicerState | Get and set visual slicer state. |