Enhance your users' experience with bookmarks

  • Article

Report bookmarks in Power BI let you capture the current state of an embedded report page, including all filters and the state of its visuals. When you open the report at a later time, you can select the a bookmark to restore the report to the saved state. Developers can control the user experience by using the Power BI Client APIs to capture and apply bookmarks.

A saved bookmark can either be a bookmark that was saved as part of a report or a bookmark that was captured as a real-time state of a report. If you apply a saved bookmark when you load a report, you can specify the bookmark to use by providing either the bookmark's name or its state. If you provide a bookmark by name, your report needs to contain a saved bookmark with that same name.

This article explains the different API settings you'll need to embed reports that support bookmarks.

Note

In reports you embed for your organization, report consumers create personal bookmarks by capturing the state of the report, and quickly returning to that state by selecting the bookmark. See Personal bookmarks for more information.

For information on how to create a similar experience in reports you embed for your customers, see the capture report view showcase in the Power BI embedded analytics playground.

For more information about using bookmarks in Power BI, see Create bookmarks in Power BI Desktop.

For information about using personal bookmarks when embedding Power BI, see Personal bookmarks.

How to use report bookmarks

The following sections show how to use the Power BI Client APIs to work with report bookmarks.

Manage a report's bookmarks

To manage a report's bookmarks, use the bookmarksManager property of an embedded report instance.

The BookmarksManager class has the following methods:

  • getBookmarks - Returns a list of saved bookmarks associated with the report.

  • apply - Applies by name a previously saved bookmark to the report.

  • capture - Captures and returns a base64-serialization string, which represents the current state of the report.

  • applyState Applies a previously captured base64-serialization state of a bookmark to the report.

  • play - Controls the slide show presentation mode for the report's bookmarks.

Access a report bookmark

To access an individual bookmark, use the getBookmarks method to access a list of ReportBookmark objects. The ReportBookmark class has the following properties:

  • name - The unique identifier of the report bookmark.

  • displayName - The display name of the report bookmark, which appears in the Bookmarks pane.

  • state - A base64 serialization of the report bookmark's state. You can save it and apply it to a report with the bookmarksManager.applyState method.

  • children - A list of ReportBookmark objects representing a report bookmark group, if it exists.

Use the report bookmarks APIs

In an embedded report, developers can:

Get a list of saved report bookmarks

To get the list of saved bookmarks associated with a report, call the getBookmarks method of the BookmarksManager object returned by the report's bookmarksManager property.

The getBookmarks method is defined as follows:

getBookmarks(): Promise<models.IReportBookmark[]>

For example:

let bookmarks = await report.bookmarksManager.getBookmarks();

Apply a saved bookmark by name on report load or during a session

To apply a previously saved bookmark to a report by using its bookmark name, call the apply method of the BookmarksManager object returned by a report's bookmarksManager property.

For more information, see Configure report settings.

The apply method is defined as follows:

apply(bookmarkName: string): Promise<void>

For example:

await report.bookmarksManager.apply("Bookmark1234");

Capture and get a current view as a bookmark object

To capture the current state of a report as a base64 string, call the capture method of a BookmarksManager object. The capture method returns an IReportBookmark object, which represents a bookmark that's not saved in a specific report. Use the IReportBookmark.state property to return the base64 string identifying the bookmark state, which you can later apply to a report during load time or run time.

The capture method is defined as follows:

capture(options?:ICaptureBookmarkOptions): Promise<models.IReportBookmark>

For example:

let capturedBookmark = await report.bookmarksManager.capture();

Capture bookmark options

You can also pass an ICaptureBookmarkOptions object to the capture method.

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages - By default, the captured bookmark state will save only the current page state. To capture the state of all pages, call capture method with allPages option set to true.
  • personalizeVisuals - To capture the current state with personalized visuals, call the capture method with the personalizeVisuals option set to true.

For example, the following code captures the state of all pages, including the personalized visuals:

let capturedBookmark = await report.bookmarksManager.capture({
    allPages: true,
    personalizeVisuals: true
});

Apply a captured bookmark state on report load or during a session

To apply a previously captured bookmark state to a report, use the applyState method of a BookmarksManager object.

For more information, see Configure report settings.

The applyState method is defined as follows:

applyState(state: string): Promise<void>

For example:

await report.bookmarksManager.applyState(capturedBookmark.state);

Perform additional logic when a report bookmark is applied

To determine when a report bookmark has been applied, listen for the bookmarkApplied event by calling the on method of the report object.

For example:

report.on("bookmarkApplied", (event) => {
    console.log(event.detail.name);
});

Show or hide the Bookmarks pane

To show or hide the Power BI Bookmarks pane, update the panes property of the report settings.

Show the Bookmarks pane

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: true
        }
    }
};

Hide the Bookmarks pane

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: false
        }
    }
};

For information about updating report settings, see Configure report settings.

Enter or exit bookmarks slide show mode

To control the slide show presentation mode for a report's bookmarks, call the play method of a BookmarksManager object. For more information, see Bookmarks as a slide show.

The play method is defined as follows:

play(playMode: models.BookmarksPlayMode): Promise<void>

Note

Before entering bookmarks slide show mode, make sure that there is at least one bookmark on the report with getBookmarks API.

Enter slide show presentation mode

await report.bookmarksManager.play(models.BookmarksPlayMode.Presentation);

Exit slide show presentation mode

await report.bookmarksManager.play(models.BookmarksPlayMode.Off);

Limitations

  • When you use the bookmarks API, certain changes to the report can cause an error or an unexpected result. One example of this is removing report filters from the report. To avoid errors, the corresponding filter cards must be present. Instead of removing the filters, set their values to All. If you don’t know which filters were deleted or changed, recapture the bookmark after you apply the changes to the report.

  • Filters such as on load filters created by the embed session or added by the update filters add operation, are captured in the bookmark state but will be applied only in the current session. To overcome this limitation, the filter should be saved on the report with the All value, and modified in the embed session using the update filters update operation.

Next steps