Phased Embedding

Background

Usally the loading of an embedded artifact is done using powerbi.embed.

var config = {
    type: 'report',
    tokenType: TokenType.Embed ,// or TokenType.Aad
    accessToken: ...,
    embedUrl: ...,
    id: ...,
    ...
};
 
// Get a reference to the embedded report HTML element
var embedContainer = $('#embedContainer')[0];
 
// Embed the report and display it within the div container.
var report = powerbi.embed(embedContainer, config);

Once called, the embedded object is loaded in front of the end-user, and any interaction with the object is done while shown to the end-user.

To improve the end-user experience and provide more flexibility for developers, we have extended this flow with API calls that adds phases to the embedding process for report embed.

Load

powerbi.load(...) allows you to stop the report from rendering, and to interact with the report before the end-user can see the results.

For example, you can use it to get pages and then decide which page to show the end-user.

This function requires an HTML element and an IEmbedConfiguration object (See Embedding Configuration) similar to powerbi.embed(...).

// Building the config object
var config = {
    type: 'report',
    tokenType: TokenType.Embed,
    accessToken: ...,
    embedUrl: ...,
    id: ...,
    ...
};
 
// Get a reference to the embedded report HTML element
var embedContainer = $('#embedContainer')[0];
 
// Embed the report and display it within the div container.
var report = powerbi.load(embedContainer, config);

...
report.on("loaded", function() {
    var page = report.getPages();
    ...
}

Once the load is completed, a 'loaded' event will be fired (see Handling Events).

Render

Finally, in case you used powerbi.load(), you will need to use report.render() to continue the report rendering.

A 'rendered' event will be fired once the render is completed (see Handling Events).

report.on('loaded', function() {
   // Now we can call render()
   report.render();
});

report.on('rendered', () => {
    ...
});