Chapter 14: Embedding in Applications

In the previous chapter, we had a close look at reserved capacities in Power BI, which are sold under the Power BI Premium and Embedded product lines. We learned about the additional features they offer, focusing on those that help with scalability and performance. We also learned how capacities manage resource usage and overload, as well as how to monitor, optimize, and scale.

In this chapter, we will learn how to optimize for embedding, a capability that extends the reach of Power BI. This allows developers to use Power BI APIs to embed reports, dashboards, or tiles into their custom applications. There are many possible uses of this, with popular choices being serving analytical content within company intranets, public-facing websites, or even commercial applications.

Embedding is technically possible with any Power BI capacity, so you don't need to buy Premium or Embedded to try it. However, for this to work properly at scale, you need to purchase reserved capacity to get around the limits of shared capacities, such as a limited number of embed tokens. Hence, the material in this chapter is relevant to the Premium and Embedded capacities. We will not cover Publish to Web, which is intended for mass distribution and behaves differently.

We will discuss what embedding involves, why there are special considerations, and how to make sure that Power BI content is loaded into the external application as quickly as possible. We will also learn how to monitor Embedded content to identify areas that are slowing you down.

In this chapter, we will cover the following topics:

• Improving Embedded performance
• Measuring Embedded performance

Improving Embedded performance

Embedding content in external applications gives organizations more flexibility in how they deploy and consume Power BI. There are different deployment, cost, and licensing considerations that will affect which type of capacity you purchase. Microsoft effectively provides reserved capacity offerings that are catered primarily to externally sharing content versus internally sharing content. However, the Embedded functionality and mechanisms that are used to surface and optimize the content are the same. Hence, the advice that will be provided in this chapter can be considered as generally applicable. If you would like to learn more about embedding licensing and distribution models and which capacity type is best for you, please check out the following documentation: https://docs.microsoft.com/power-bi/developer/embedded/embedded-faq.

Embedding content using APIs is an alternate way to expose content where you don't use Power BI's web frontend. This can be seen in the following diagram:

Figure 14.1 – Embedding Power BI content in other applications

In this configuration, users are interacting with the external application and not directly on powerbi.com. Once the content has been initialized within the external application, performance is not affected by that application, unless it is also competing for CPU on the client.

Note

When you're embedding content, you should optimize it the same way as you would any other Power BI content. Follow all the guidance we have provided around data modeling, loading, report design, and so on. It is also important to perform capacity planning and sizing using the methods described in the previous chapter.

However, there are additional considerations regarding how the application is configured with Power BI and how it interacts with Power BI Service. Next, we will learn why embedding is different and how we can speed it up.

When we embed Power BI content in another application, we are adding another layer of processing and latency. When we view a report on the Power BI website, under most conditions, the Power BI application is already bootstrapped. This means that the core application code and dependencies have already been loaded. However, when we load Power BI on-demand within our applications, this may not be the case. There may also be some overhead and latency between your application and the Power BI services. This includes time taken by your application before it even calls Power BI, where users can see other content already. This has the effect of exaggerating the delayed experience of loading Power BI content. Therefore, the advice we will give focuses on minimizing the embedding overhead.

The following list provides guidance and rationale for optimizing Embedded scenarios:

• Consider Application Location and Architecture: The bi-directional arrow shown in the preceding diagram represents communications and data transfer between Power BI and your custom application. You should minimize communication latency by placing the custom applications as close to the Power BI home region as possible. This includes ensuring the number of network hops is minimized and sufficient bandwidth is available between Power BI and the custom app. Do keep in mind that visuals are executed on the client side, so if you have users in different geographic locations, some may have a different performance experience for the same content.
• Keep SDK Packages and Tools up to Date: The Power BI team regularly updates both client tools and services, as frequently as monthly. These updates often contain new features, but they do contain performance improvements as well. When you deploy an application with Embedded content, it's easy to continue updating the content without looking at the embedding mechanisms. To avoid missing out on embedding improvements, we recommend using the latest SDK, API versions, and authoring tools, such as Power BI Desktop. The SDK can be found at https://www.nuget.org/packages/Microsoft.PowerBI.Api, while the client libraries for embedding can be found at https://docs.microsoft.com/javascript/api/overview/powerbi.
• Preload Dependencies: The Power BI Embedded API provides a method called powerbi.preload that allows you to load core Power BI dependencies on demand. This is useful when you have a custom application that does not display Power BI content immediately to users. If you know your users are likely to eventually reach Power BI content, you can improve the first load experience. You can do this by calling powerbi.preload when you initialize the application, but before your users reach areas that display Power BI content. This will load JavaScript files, CSS stylesheets, and any other artifacts and cache them locally. When the application needs to show Power BI content, it can avoid fetching the dependencies first. Additional information about preloading can be found here: https://docs.microsoft.com/javascript/api/overview/powerbi/preload.

  Note

  Use preload only when the Power BI content is on a different page of the application. It is best to bootstrap the iFrame when possible, as described in the next point.

• Bootstrap the iFrame: Embedding uses an HTML construct called an iFrame to host Power BI's content. An iFrame is used to embed one HTML document within another and is typically used to expose external content that's served from a different web location or server. For example, you could use it to embed the Google search home page into a section of your website.

When you embed content using powerbi.embed, you need a report identifier, an embed URL, and an access token. Not all of these are immediately available, depending on the application's design and user journey. When you call the powerbi.embed method, the iFrame is prepared and initialized before the content loads. However, it is possible to perform this initialization earlier using powerbi.bootstrap(element, config). You must provide it with an HTML element and an Embedded configuration object as parameters. When all the required parameters are ready, you can call powerbi.embed, passing in the same HTML element that has been already initialized. This is a great way to prepare for Power BI content to be displayed in the background while the user is doing something else in the application. Depending on the application's architecture and configuration, this can save some precious seconds, making a big difference to the user experience.

• Use Embed Parameters Effectively: The second parameter in powerbi.embed(element, config) allows you to set options that control what features are enabled in the Embedded content. The properties of the configuration object that affect performance are as follows:
  • EmbedURL: This property is the URL of the content you are embedding and is assigned to the src attribute of the iFrame. Avoid generating this URL yourself. You can obtain the best URL from the service using the Get reports, Get dashboards, or Get tiles APIs.
  • Permissions: This property determines which operations you grant the person viewing the content. Use the Read permission if the user does not need to create content or copy or edit the report. This avoids initializing UI components that are not needed. Similarly, only set the minimum permission level that's needed if they require editing rights.
  • Slicers, filters, and bookmarks: These are separate properties in the configuration that allow you to set the context for the content. By design, Power BI tries to cache visuals to speed up report content while queries are executed in the background. This cached result considers the report's context set by slicers, plus more. However, if you are embedding and supplying this context via the code, the cache is not used. Therefore, if you have a default starting context for an Embedded report, you should publish the report with that context already set. Then, you can call the embed method without context to take advantage of the cache.
• Change Reports Efficiently: A custom application allows you to build interesting functionality, such as a custom navigation UI that controls which Power BI reports a user sees. A user could simply click a button or a link to replace the current report, without reloading the page. If you implement something like this, ensure that you reuse the iFrame. When you call powerbi.embed, use a different configuration but pass it the same HTML element.
• Use a Custom UI to Reduce Slicer Complexity: You can reduce the complexity of reports by removing slicer visuals from the report canvas and setting them in the Embedded report configuration object described earlier in this list. This lets you capture a lot of different slicer and filter selections and pass them all at once while you're loading the initial Embedded report.
• Throttle the Custom Application to Prevent Misuse: Users can double-click custom report links or navigate between reports in the custom app very quickly, causing many calls to be issued to Power BI's backend. You can limit this kind of behavior in your application by setting a short duration within which to ignore a user action that occurs too soon after the last one. A good rule of thumb here is about 100 ms.
• Handling Multiple Visuals: Many reports contain more than just visuals. You can embed a page containing multiple visuals as it was designed within a single iFrame. However, you may need to combine embed multiple reports or even individual tiles in your custom application, interspersed with other content. If you Embedded each one separately, each would need an iFrame. Initializing an iFrame is relatively expensive, so you should try to have as few as possible. Here are some options:
  • Consolidate reports: If possible, consolidate data and visuals from separate datasets and reports. This will allow you to embed the content in one iFrame.
  • Use a dashboard to combine disparate content: A Power BI dashboard is designed to contain report tiles from different reports and datasets that have no technical relationship with one another. If you need to embed tiles from different reports into your application, consider putting them in a dashboard and embedding it instead of all the individual tiles. This reduces the load to a single iFrame. You can also embed individual tiles from dashboards instead of reports. These are more efficient than report tiles and will load faster. Consider this option when you do not want all the tiles appearing together in your application and you don't want to use multiple iFrames.
  • Use a Custom Layout: The Embedded config has a layoutType property that can be set to customLayout. The latter allows you to define a page's size and visual layout, which will override the defaults. It even allows you to hide visuals you don't want to see. It is also useful to rearrange visuals so that they can be viewed on mobile devices. More information on setting a custom layout can be found here: https://docs.microsoft.com/javascript/api/overview/powerbi/custom-layout.

Now that we know how to optimize embedding scenarios, let's learn how to gauge embedding performance.

Measuring Embedded performance

When you embed Power BI content in your applications, it is recommended that you measure the embedding activity to understand the performance profile. The methods we have described in this book can help you measure and resolve the performance of the Power BI artifacts themselves, but they do not tell you what is happening in your application and if there is any inefficiency when it is communicating with Power BI and loading content. For example, the Embedded Power BI report may execute queries and render visuals within 2 seconds, but the user experiences a longer total wait time due to the embedding overhead. Before we learn how to measure the embedding overhead, we will introduce a recommended practice.

Important Note

When you're performance tuning your Embedded content, it is very important to obtain a baseline of performance without embedding. This will help you set the appropriate range for the best case in performance, as well as help you identify any issues unrelated to embedding. You can optimize their datasets, DAX, and so on, independently and in parallel to the embedding optimization. Just be sure to optimize the embedding code in your web application using the same Power BI content all the time. This way, you can ensure that any improvements are from the embedding changes, and not from Power BI content changes.

When you embed Power BI content, the system generates events to help you track and optimize embedding behavior. To learn more about capturing Embedded events, please see the following documentation: https://docs.microsoft.com/javascript/api/overview/powerbi/handle-events.

Next, we will describe the relevant events and how they can help with performance tuning:

• Loaded: This event fires when a Power BI report or dashboard has been initialized. Loading is complete when the Power BI logo shown in the following screenshot is no longer shown:

Figure 14.2 – The Power BI logo and progress bar that's shown when a report has been initialized

• Rendered: This event is raised after the report visuals have completed any work and displayed their results on the screen.
• VisualRendered: This event is fired for every visual. It is not enabled by default and needs to be enabled by setting visualRenderedEvents to true in the embedding's configuration. This allows you to track the speed of each visual, as well as rank the visuals and focus on the slowest ones. This information can also be gained from Desktop Performance Analyzer and is a good way to compare the performance of content that's deployed to production versus in development.

Now, let's learn how to use events to understand where delays are occurring. We suggest using a combination of the Power BI events we described in the previous list, plus the events that you manually generate in the custom application. This will give you a complete picture of all activities. The following diagram shows a timeline representation of a user action in a custom application. In this example, we assume that a user has clicked a button in the custom web application (not a Power BI report), which makes the calls to load a Power BI report that contains two visuals:

Figure 14.3 – Timeline of embedded activity and event generation

The preceding diagram shows a Custom Start Event and a Custom Finish Event. These represent the entire user action from the time they clicked the custom button to the time the custom web app finished its work. There may be other work besides loading the Power report, which is why we have included a gap between the Rendered event and Custom Finish Event.

Once you have captured these events, you can subtract the timestamps to work out the duration of any component. Then, you can compare this to the results of the service, as well as in Performance Analyzer, to see if there is a substantial difference.

Now, let's summarize what we've learned in this chapter.

Summary

In this chapter, we concluded our Power BI optimization journey by learning how to embed content efficiently. We learned that reserved capacities that are sold under the Premium and Embedded product lines allow developers to embed content in external applications. This allows them to build their own user experience that's been enhanced by analytical content from Power BI. When they do this, they avoid using the Power BI user interface, and users access reports through the custom application. We learned that it is important to plan for and optimize Embedded capacities and the content they host per all the guidance provided earlier in this book.

Then, we learned that embedding involves communication between Power BI Service and the custom application via APIs. The Embedded SDK allows developers to authenticate against Power BI, load the Power BI base application code, and then place reports, dashboards, or tiles inside the custom application. This adds some overhead, which can be very noticeable if there is significant latency between the application and Power BI. However, we have highlighted that you can – and should – optimize your Power BI content separately to the embedding mechanisms. Ideally, this should have already been done so that you can focus on performance tuning.

We also learned that it is important to use the latest tools and SDKs when embedding to take advantage of the performance improvements that have been made by Microsoft. We also introduced the API methods that are provided by Microsoft that can be used to load or initialize Power components ahead of time. This reduces the initial load time for Power BI content by having dependent assets such as JavaScript and CSS files loaded before the user needs to view Power BI content. We also looked at configuration settings such as minimal permissions, which can speed up content by only loading the necessary UI components.

After that, we learned that when a custom application needs to load Embedded Power content, it does so in an iFrame. We discussed how every separate piece of Embedded content uses an iFrame and that it is important to minimize how many iFrames are used to reduce initialization overhead. Here, we suggested consolidating content into fewer reports or using dashboards and individual tilers, which can load faster.

Finally, we learned how to measure the performance of Embedded code. We introduced the concept of events and suggested that you use both custom events and the ones provided by Microsoft to build up a full picture. This allows you to understand the duration of the entire operation from the user's perspective and break out report initialization, overall rendering, and the duration of individual visuals.

Final Thoughts

Congratulations! You have completed your Power BI optimization journey and should be ready to tailor and apply what you've learned to your work. We will close with a reminder that performance management should be a discipline that is ingrained into every stage of your development life cycle. You can achieve great results and maintain good designs with a bit of planning and strong collaboration between stakeholders with different roles and skillsets.