Use bootstrap for better performance

  • Artikel

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.

Bootstrap API

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;

Bootstrap embed configuration

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.

Bootstrap samples

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

Limitations

  • 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.

Next steps