Back in August 2015 we open sourced our data visualization stack, documented the IVisual interface, and let developers start building custom visuals for Power BI. In October 2015, we enabled a preview that allows business users to import custom visuals into reports, and later in January 2016 we allowed the usage of custom visuals in dashboards. We’ve seen tremendous momentum with custom visuals, with end users, solution integrators, and ISVs all integrating their work with Power BI so users have access to faster, repeatable data driven decision making tools.
We’ve also seen developers do weird and wonderful things with our APIs, both documented and undocumented. However, issues can arise when multiple custom visuals are all on the same page or in the same report. Even well-meaning developers can inadvertently cause various conflicts: CSS conflicts, unexpected .JS interactions, or relying on interfaces that were not documented, but that happened to resolve in our developer tools. All of these issues lead to glitches for end users and bugs that we’re seeking to avoid.
As we plan ahead for the custom visuals feature with the goal of bringing it out of preview later this year, you should be aware of a few steps that we’re taking now to prepare. The first change to roll out is sandboxing of custom visuals. In this blog I’ll describe the details of what sandboxing is, how you can test your visual, and how you can provide us feedback on any issues you encounter so we can help you adapt your code or fix underlying bugs in our sandbox. The second change, which I’ll get to at the end of this post, is preparing for the ‘V1’ custom visual API.
Sandboxing of custom visuals
What is sandboxing for custom visuals?
Sandboxing provides a layer of isolation for each custom visual by hosting it in a dedicated iFrame. Your code and dependencies are injected dynamically into the iFrame. It ensures you don’t have conflicts with other visuals/elements on your page and removes access to APIs that you shouldn’t be using in your custom visuals.
When will sandboxing be enabled for custom visuals?
We expect to enable sandboxing on or around March 22, 2016. We’ll adjust this based on your feedback and any reported issues.
What is the impact on my custom visual?
Sandboxing runs your visual’s code in a low privilege iFrame with no domain. You will not be able to assume access to Power BI styles (CSS), Power BI fonts, or undocumented Power BI APIs. We will inject all the required interfaces into the iFrame, including your visual’s code, and then marshal data points and required settings across the iFrame boundary. Since the iFrame has no domain, you will not have access to cookies or local storage. Finally, how you debug your custom visual will change a little, which I’ll cover below.
Here’s an example iFrame into which your visual will be loaded:
<iframe class=”visual-sandbox” src=”/sandbox?plugin= MyVisualName” style=”width: 1177px; height: 682.04px;” sandbox=”allow-scripts”></iframe>
How can I test my visual in the sandbox?
Starting right now you can test your visuals, dashboards, and reports in the sandbox by adding a flag to the URL in the address bar. Follow these steps:
- Sign-in to your Power BI account
- Paste the following URL into your browser address bar: https://app.powerbi.com/?sandboxVisualsEnabled=1 and press Enter
You know the feature switch successfully applied if after the browser loads the flag is in the URL. For example:
https://app.powerbi.com/groups/me/dashboards/5f3627e4-a662-4111-a5ea-39ef2833fe24?sandboxVisualsEnabled=1
Please note that if you needed to sign-in in step #2, the feature switch will not be applied. You can click the URL again, or just paste ?sandboxVisualsEnabled=1 on the URL and refresh.
How do I debug in the sandbox?
The easiest way to debug is to add the following line of code to your visual’s init method or wherever you’d like a breakpoint for the browser’s debugger: debugger;
Then, when you’d like to debug your visual, launch the browser’s debugger, add your visual to the page and bind some data to it. The debugger will automatically break when init is called by Power BI, allowing you to see your code. Without this, you may find it hard to identify where the code is located in the browser’s debugger, since it is dynamically injected into the iFrame.
A note about unhandled exceptions
It is important for you to add hardening for unhandled exceptions to your visuals. To keep the iframe and the host page in sync, we run synchronization code in the iFrame alongside your visual’s code. If your visual throws an unhandled exception, we attempt to catch it so our synchronization code keeps working, and even then your code might not work in the resulting state. We’ve found that some custom visuals have unpredictable behaviors after they throw an unhandled exception but since it’s your code we’re not able to fix those issues on our side.
The most common symptom of this is the visual stops resizing correctly when the user resizes the visual in Power BI. If you see this happening, check if the custom visual is throwing exceptions and resolve those before submitting an issue.
Known issues
We’re still fixing some bugs in the sandbox and will be rolling out fixes in the coming weeks. These fixes should not affect your ability to test your visuals. The list of known issues is maintained in a post on the Power BI Community.
How to report issues
Please report issues on the official thread in the Power BI community. This will give us the ability to track and respond to issues.
Feedback on “V1” custom visuals APIs
We’ve seen many wonderful custom visuals created by many people all over the world. We’re always amazed by your work, and how it enhances reports and helps users make better decisions.
With several months of preview interfaces in the market, we’re looking to create a ‘V1’ API that we can fully support for the long term. The goal is to create a simpler API that is more clearly documented, with stable non-breaking interfaces.
To do this, we need your help. We’ve monitored feedback on https://ideas.powerbi.com, the Power BI community, Stack Overflow, and issues from our GitHub repo, and we’re really thankful for all of the feedback so far. Now we’d like to hear more directly from you about what you’d like us to include future versions of the Custom Visuals APIs. Please respond to the Custom Visual API post in the Power BI community with your suggestions and ideas so we can discuss them.