Use bootstrap for better performance
powerbi.bootstrap
is a method introduced in Client SDK version 2.9.0 to help developers embed Power BI entities faster and get better performance.
Embedding a report using powerbi.embed
requires multiple parameters, such as reportId
, embedURL
, and accessToken
. These parameters aren't always immediately available.
powerbi.bootstrap
allows you to start embedding before all the required parameters are available. The bootstrap API prepares and initializes the iframe.
After the required parameters are received, powerbi.embed(element, config)
should be called on the same HTML element.
The powerbi.bootstrap(element, config)
method receives an element and config, the same as powerbi.embed(...)
.
/**
* Given an HTML element and entityType, creates a new component instance, and bootstrap the iframe for embedding.
*
* @param {HTMLElement} an HTML Element where you need to embed. must be the same div element you will use in powerbi.embed.
* @param {IBootstrapEmbedConfiguration} config: a bootstrap config.
*/
bootstrap(element: HTMLElement, config: IBootstrapEmbedConfiguration): embed.Embed;
interface IBootstrapEmbedConfiguration {
type: string;
hostname?: string;
embedUrl?: string;
settings?: ISettings;
}
Config parameters:
- type (required): The type of entity you want to embed, such as 'report', 'dashboard', 'tile', 'qna', or 'visual'.
- hostname: If you don't have an
embedURL
yet, you can provide a hostname. The hostname is the domain name of the embed URL. For example, if the embed URL is 'https://app.powerbi.com/reportEmbed' then the hostname is 'https://app.powerbi.com/'. If no hostname or embedUrl is provided, the default hostname,https://app.powerbi.com/
, is used. - embedUrl: The same embed URL you will provide later to powerbi.embed. If no hostname or embedUrl is provided, the default hostname,
https://app.powerbi.com/
, is used. - settings: To embed the report in a mobile layout or to provide a locale (language), include these parameters in the initial settings.
The following samples provide a reference for the bootstrap method when embedding Power BI entities.
Note
Make sure that you call powerbi.embed
after receiving the embed parameters.
To bootstrap for embedding a report:
powerbi.bootstrap(
reportContainerDivElement,
{
type: 'report',
}
);
To bootstrap for embedding a dashboard:
powerbi.bootstrap(
reportContainerDivElement,
{
type: 'dashboard',
embedUrl: "https://app.powerbi.com/dashboardEmbed?dashboardId=06e3ba63-47ea-4579-b010-fdb5484b325a&config=eyJjbHVzdGVyVXJsIjoiaHR0cHM6mLndpbmRvd3MubmV0In0="
}
);
To bootstrap for embedding a report with the hostname only:
powerbi.bootstrap(
reportContainerDivElement,
{
type: 'report',
hostname: "https://app.powerbi.com"
}
);
To bootstrap for embedding a report with mobile layout:
powerbi.bootstrap(
reportContainerDivElement,
{
type: 'report',
hostname: "https://app.powerbi.com",
settings: {
layoutType: models.LayoutType.MobilePortrait
}
}
);
The following bootstrapped entities cannot be changed without calling
powerbi.reset(element)
.- Component type (report, dashboard): For example, if you bootstrap a report, you can only embed reports in the same HTML element.
- Layout (desktop/mobile)
- Locale (language)
The
powerbi.bootstrap
method isn't supported when embedding paginated reports.