Share via

Use phased embedding

  • Article

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();
});

Considerations and 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.

Related content