From BI Book 13.3 release, private embed links include two settings for working with bookmarks:

• Show bookmarks menu: Turn this on to give viewers a built-in menu for managing bookmarks directly in the embedded report.

• Allow bookmark management through JS: Turn this on to let your developers create, view, list, update and delete report bookmarks using the BI Book JavaScript library. Use this when you want to build bookmark controls into your own app instead of using the built-in menu.

How to use JS code embedding

• Script code structure

<script src="https://<bibook-address>/embed.js?token=<TOKEN>" data-width="100%" data-height="540px"></script>

Behavior:

• The script inserts the frame immediately after the <script> tag, so place the tag where the report should appear.

• Only token, refresh and filter are passed on. locale and page are dropped; use the iframe if you need them.

• For multiple reports on one page, add one script tag per report, and give each one a data-name if you use the JavaScript API.

Requirements on the host page:

• Use a plain <script> tag: no async or defer, and do not inject it from another script.

• The host's Content Security Policy must allow script-src and frame-src for the BI Book domain.

Example:

<script src="https://<bibook-address>/embed.js?token=<TOKEN>&refresh=1h&filter=Sales%2FRegion%20eq%20'North'" data-height="80vh"></script>

How to use JS library for managing bookmarks

The host page can manage bookmarks from its own code. The API is available only when all of these are true:

1. The link is private.

2. The link was created with Allow bookmark management through JS.

3. The report is embedded with the JS code

Getting the API

Each script tag registers its report on the global window.BBEmbed object.

// the report whose <script> has data-name="sales"; without an argument, the first report on the page 
const report = window.BBEmbed.getReport('sales'); 
const bookmarks = await report.ready(); // resolves once the report has loaded

• getReport(name) returns null when no script tag has that data-name.

• ready() resolves with the bookmarks API after the report loads. It never resolves for a link without JS management, or while the viewer is not signed in.

• Every API method rejects with BBEmbedWidget: bookmarks are not available until ready() has resolved.

Methods

Every method returns a promise.

Bookmark object:

Changes made through the API also appear in the bookmarks menu (when shown) and in BI Book.

Errors

A rejected promise carries an Error whose message is one of these codes:

A server-side validation error is passed through as its own message instead of request_failed.

Rules for host code

• Place the API code after the embed script tag, so window.BBEmbed exists when it runs.

• Wait for ready() before calling any method.

• ready() never resolves for a link without JS management, so do not block the page on it.

• Bookmark ids are numbers.

• Every method can reject. Handle the error codes listed above.

JavaScript API examples

The snippets below show how each part of the API is used. They are illustrations, not ready-made code.

Add the script

Embed the report with the script code from the Get link dialog, and give it a name:

<script src="https://<bibook-address>/embed.js?token=<TOKEN>" data-name="sales"></script>

With several reports on one page, each script tag gets its own name:

<script src="https://<bibook-address>/embed.js?token=<SALES_TOKEN>" data-name="sales"></script> <script src="https://<bibook-address>/embed.js?token=<STOCK_TOKEN>" data-name="stock"></script>

data-name is optional with a single report.

Get the bookmarks object

Find the report by its name, then wait until it is ready. ready() resolves with the bookmarks object:

const report = window.BBEmbed.getReport('sales'); 
const bookmarks = await report.ready();

Without a name, getReport() returns the first report on the page:

const report = window.BBEmbed.getReport(); 
const bookmarks = await report.ready();

Step by step

Each step keeps its result in its own variable, so the next step can use it:

<script src="https://<bibook-address>/embed.js?token=<TOKEN>" data-name="sales"></script> 

<script type="module">  
   const report = window.BBEmbed.getReport('sales');  
   const bookmarks = await report.ready();  
   const items = await bookmarks.getBookmarks();  
   const firstBookmark = items[0];  

   await bookmarks.applyBookmark(firstBookmark.id); 
</script>

type="module" allows await directly in the script.

List bookmarks

const items = await bookmarks.getBookmarks(); 
// [ 
// { id: 12, name: 'Q3 North', private: true, linked_report_id: null }, 
// { id: 15, name: 'Budget', private: false, linked_report_id: null }, 
// ]

private: false marks a shared bookmark.

Get one bookmark

const bookmarkId = 12; 
const bookmark = await bookmarks.getBookmark(bookmarkId); // { id: 12, name: 'Q3 North', private: true, linked_report_id: null }

Create a bookmark

The new bookmark saves what the viewer sees at that moment: page, filters, slicers and selections.

// private bookmark, visible only to the viewer 
const privateParams = { name: 'Q3 North' }; 
const privateBookmark = await bookmarks.createBookmark(privateParams); 

// shared bookmark, needs bookmark editing rights on the report 
const sharedParams = { name: 'Q3 North', private: false }; 
const sharedBookmark = await bookmarks.createBookmark(sharedParams);

Update a bookmark

const bookmarkId = 12; 

// rename it
const renameParams = { name: 'Q3 North (final)' }; 
const renamed = await bookmarks.updateBookmark(bookmarkId, renameParams); 

// replace its saved view with the current one 
const captureParams = { captureState: true }; 
const recaptured = await bookmarks.updateBookmark(bookmarkId, captureParams); 

// both at once 
const bothParams = { name: 'Q3 North (final)', captureState: true }; 
const updated = await bookmarks.updateBookmark(bookmarkId, bothParams);

Each call resolves with the updated bookmark.

Apply a bookmark

const bookmarkId = 12; 
await bookmarks.applyBookmark(bookmarkId);

Delete a bookmark

const bookmarkId = 12; 
await bookmarks.deleteBookmark(bookmarkId);

Handle errors

A failed call rejects with one of the codes listed above as the error message:

try {  
   const params = { name: 'Q3 North', private: false };  
   const bookmark = await bookmarks.createBookmark(params); 
} catch (error) {  
   const errorCode = error.message; // 'public_not_allowed' 
}