When using PaaS model the tokens issued are for a specific report or tile and the token should be associated with the embed url on the same element to ensure each has a unique token allows embedding multiple reports using the same service instance.
When using SaaS model the tokens issued are for a specific user who can view many types of visuals. This means you can add this as a global token reused for all embedded visuals as shown below:
It is not required, but you can assign global token on instane of Power BI servic which will be used as a fallback if a token isn't provided for the specific instance.
var report = powerbi.embed($reportContainer.get(0), embedConfiguration);
```
> Note: You can still choose to supply a SaaS access token (issued by AAD instead of your own service) in the embed configuration. This allows you to have apps that embed reports using SaaS and PaaS authentication.
> Also, notice how the embed experience across both SaaS and PaaS is nearly identical except for how you specify the access token.
FilterPane is enabled/visible by default but can be disabled/hidden by adding the attribute on the element or specifying the setting in the embed configuration:
Embedded components will emit events after a command invoked on it has been executed and the operation completed. These commands could be sent programmatically through the SDK or from the user directly interacting with the report.
Example: The user can manually change pages by using the built-in page navigation and clicking on the buttons, or you can programmatically change the page by sending the correct postMessage. In both cases a `pageChanged` event will occur.
It is required to wait for the report to be fully loaded before you can send it commands. This is very similar to waiting for the DOM to be ready before attempting to take action on the elements.
In order to do this you must listen for the loaded event and then issue new commands.
What actually happens when you call `powerbi.embed(element, embedConfig);`?
1. Determine if we are embedding on an element which is contains embedded content.
If the content already embedded is of the same type, we can re-use the existing iframe and simply send a new load command to it rather than reloading the entire contents of the iframe which is much slower since there is significant amount of JavaScript to download.
2. (New Embed) Create instance of embed object.
The [constructor](https://github.com/Microsoft/PowerBI-JavaScript/blob/dev/src/embed.ts#L67) of the embed will normalize all the required configuration from either the HTML attributes or those passed directly in the configuraiton object.
(Existing Embed) Pass through to next step.
3. Call `embed.load` which will take the normalized load configuration and send the load message to the iframe.
// TODO: Insert flow-chart diagram
# Understanding the object hierarchy
The core of the library is a service which is responsible for tracking the embeds in the application, handling communication to and from their iframes, and also handling event bubbling.
The embeds that the service tracks are all implementations of the abstract `Embed` class. Concrete implementations of this class are things that you are familiar with in Power BI such as Reports and Dashbaords.
Within these top-level embed objects, the have a logical composition of other objects. For example: Reports have pages and pages have visuals and each of these objects has different types of actions that can be performed on it.
// TODO: Insert UML and Block Diagrams
# Understanding the post message communication flow
Although `powerbi-client` is bundled as a single script for ease of use there are 4 other dependent libraries which enable familiar Promise-based programming style for communication accross windows.
Check out those repositories for individual descriptions and example usage.
In summary, we simulate HTTP protocol over window.postMessage.
This makes reasoning about message structure intuitive for web developers instead of being another arbitrary protocol.
This also makes the understanding the flow just like any other client server relationship.
Examples:
- Getting pages on a report: `GET /report/pages`
- Getting visuals on a page: `GET /report/pages/ReportSection/visuals`
// TODO: Include sequence diagram with requests flow and possible returns
There is more complexity in understanding the communication flow when the requests are state changing operations such as changing pages or setting filters. These operations can be initiated programmatically by the SDK or manually by the user and in order to have a constent way of dealing with this in code the API's are asynchronous.
This means instead of request and response, it is commands and events.
In the case of the SDK sending the command it will only be validated and immediately return 202 Accepted response. Meanwhile, the embed will execute the operation and when complete it will send an event.
In the case of the user initiating the command, only the event will be emitted.
Page change example:
```javascript
// Register event handler for page change events.
// Will execute regardless of the event being initated programmatically or by the user.
report.on('pageChanged', event => {
const page = event.detail.newPage;
console.log(`${page.name} was set as active page`);
// ... update ui with new page
});
// Programmatically change pages which will resolve before the page has actually changed.
