Phased Embedding API

ali-hamud edited this page Jul 3, 2018 · 5 revisions

The loading of an embedded artifact is done using ‘embed’ call, containing an embed configuration object and the <div> element that contains the iframe.

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:

Preload (Warm start)

powerbi.preload() uses the browser’s cache and download scripts prior to showing the embedded object itself. This can be proven useful for applications hosting several embedded reports. This function only requires the type of embedded entity, and a base URL for PowerBI Embedded, i.e. embed URLs without any specific URL parameters such as reportId, groupId etc.

// Create embedding config
var config= {
    type: 'report',
    embedUrl: 'https://app.powerbi.com/reportEmbed',
};

var element = powerbi.preload(config);

A ‘ready’ event will be fired once the preload is completed.

element.on('preloaded', function() {
   // do whatever you like here
});

Load metadata

powerbi.load() call helps retrieve info on the embedded object, and dynamically change any settings or the containing <div>element in the background, before the object is in front of the end-user. For example, you can use this function to get pages and then decide which page to show the end-user or get visuals and then decide on the visuals you wish to show or hide to the users. This function requires a IEmbedConfiguration (See Embedding Configuration).

// Create embedding config
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 (Same as in Handling Events). Then, you need to call the render() function to show the embedded object (see below). After the metadata loads, one can alter properties in the config and set them with the render(config) call (see below). Note the reportId & embedUrl have to remain the same.

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

Render

The final call, in case you used the powerbi.load() function, will be report.render(). This function completes the last actions needed to render and show the embedded object to the end-user. This function can receive an IEmbedConfiguration which might be different than the one used in powerbi.load(config). This allows modifying properties to better suit the metadata received in prior steps, e.g. Filters, Custom Layout, Setting pages and more. Please note, reportId & embedUrl properties MUST remain the same.

report.render();

Modifying configurations

const config = {
...
};

var report = powerbi.load(config);

report.on('loaded', () => {
    const filter = {...};
    config.filters = [filter];
    report.render(config);
});

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

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

Note

While the load and render functions should be used together, preload is independent of the prior two. You can use embed function to show the embedded object after preload, as it was done until now. One can also utilize the full phased procedure, calling preload, load & render in this respective order.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.