How to handle events
Tip
Experiment with APIs in real time using your own report or our sample report in the Developer sandbox section of the Power BI Embedded Analytics Playground.
Events are used to communicate between the Power BI component (for example, a report) and the web application code.
An embedded component emits events after an action is executed inside the component. These can be user interactions or an automated action (like a visual being rendered) within the component.
For example, buttonClicked is an event emitted by a Power BI report when a user clicks a button in the report. You can listen to the event by using report.on(...), and then set an event handler.
An example of how to handle an event
This example shows how to handle a report event. To learn about other types of events, see Events and their response values.
Note
Wait for the component to load before using the APIs. Listen to the loaded event and then issue new commands.
report.on('loaded', function(event)
{
reportPages = await report.getPages();
});
How to remove event handlers
You can use report.off(...) to remove all event handlers for a specific event.
Events and their response values
View a full list of possible events and their response values.
Error events (relevant for all embeds)
An error event is emitted to describe a failed operation.
interface IError {
message: string // A general message that describes the operation that failed (example: "Could not set page")
detailedMessage?: string // Detailed message that describes the error
errorCode?: string // Short message that describes the error
level?: TraceType // The level of the error (example: 'Fatal')
technicalDetails?: ITechnicalDetails
}
interface ITechnicalDetails {
requestId?: string // Id for debugging - should be provided when reporting a bug
}
Note
Only the message property is required, and the other properties might be undefined.
Report events
A report event is emitted for an interaction with an embedded report, such as clicking a report button or rendering a visual.
buttonClicked
The buttonClicked event is raised when a user clicks on a Report button.
id: string
title?: string
type?: string (type of button)
bookmark?: string
commandTriggered
The commandTriggered event is raised when a user clicks on an extension command.
command: string
dataPoints?: IIdentityValue[]
report: models.IReport
page: models.IPage
visual: models.IVisual
dataHyperlinkClicked
The dataHyperlinkClicked event is raised when a hyperlink is clicked, and the hyperlink's behavior is set to NavigateAndRaiseEvent or RaiseEvent.
url: string
report: models.IReport
page: models.IPage
visual: models.IVisual
For more information, see Configure report settings.
dataSelected
The dataSelected event is raised when a specific data point is selected.
report: models.IReport
page: models.IPage
visual: models.IVisual
filters: IFilter[]
dataPoints: IIdentityValue[]
loaded
The loaded event is raised when the report initializes. Loading is complete when the Power BI logo disappears.
pageChanged
The pageChanged event is raised whenever a page is changed.
newPage: Models.IPage
rendered
The rendered event is raised when a report is fully rendered. For example, if all visuals are rendered upon loading a report or after a user interaction.
saveAsTriggered
The saveAsTriggered event is raised when a user clicks on Save As in the UI. This lets you create your own dialog for the Save As action.
saved
The saved event is raised when a save is triggered by a save or saveAs action in the UI or by using the APIs.
selectionChanged
The selectionChanged event is raised whenever the user is changing the selected visual.
selectedItems is a list of all selected visuals when more than one is selected.
report: models.IReport
page: models.IPage
visual?: models.IVisual
selectedItems?: models.IVisual[]
visualClicked
The visualClicked event is raised every time a visual is clicked.
report: models.IReport
page: models.IPage
visual: models.IVisual
visualRendered
The visualRendered event is raised when a visual is rendered (requires setting visualRenderedEvents to true in the settings object).
Note
Because visuals might render due to user interactions, it's recommended that this event only be turned on when needed.
name: string
For more information, see Configure report settings.
Report Embed Mobile events
A Report Embed Mobile event is emitted for an interaction with an embedded report in a mobile layout, such as the beginning or end of a swipe.
swipeStart and swipeEnd events
swipeStart or swipeEnd events are raised when a user begins or ends a swipe movement on an embedded report.
interface ISwipeEvent {
currentPosition: IPosition
startPosition: IPosition
}
interface IPosition {
x: number
y: number
}
Dashboard events
A dashboard event is emitted when the dashboard is loaded and when a user clicks on a tile in the dashboard.
loaded
The loaded event is raised when the dashboard initializes.
tileClicked
The tileClicked event is raised when an end user clicks a tile. It is not raised for pinned live pages.
tileId: string
navigationUrl: string
pageName: string
reportEmbedUrl: string
Q&A events
A question and answer (Q&A) event is raised when a visual is rendered after entering a question.
visualRendered (Q&A)
The visualRendered event is raised when a visual is rendered after a question is entered and an answer displays.
question: string
normalizedQuestion: string
Tile events
A Tile event is raised when a user clicks on a tile.
tileClicked (tile event)
The tileClicked event is raised when an end user clicks a tile. It is not raised for pinned live pages.
tileId: string
navigationUrl: string
pageName: string
reportEmbedUrl: string
tileLoaded
The tileLoaded event is raised when the tile initializes. Loading is complete when the Power BI logo disappears.