Cloud Bookmarks
The bookmarks library is a personalization library that provides bookmarking service for the Continue Watching feature.
The library facilitates bookmarking content at different stages of playback and provides APIs to retrieve the bookmarked offset time to resume playback from the last watched position.
The BookmarkService defines the bookmarking contract and exposes APIs to perform bookmarking operations (Put, Delete & Get bookmark records).
The PlaybackSessionBookmarker composes the BookmarkService to manage bookmarking along with Player and ComposablePlayer.
Usage
Create BookmarkService
const bookmarkService = flBookmarks.createBookmarkService(
bookmarkEndPointUrl,
platformAuthorizer,
);
Create PlaybackSessionBookmarker
const bookmarksConfiguration = {
endPointUrl: endpoint,
syncIntervalMS: 5000,
thresholdPercentage: 0.95,
};
// contentId is the unique id against which bookmarking is done
const playbackSessionBookmarker = createPlaybackSessionBookmarker(
contentId,
bookmarksConfiguration,
platformAuthorizer,
bookmarkService,
);
Bookmark configuration options
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
syncIntervalMS | number | No | 5000 | Interval, in milliseconds, at which the bookmark is synced. |
thresholdPercentage | number | No | 0.95 | Fraction of the content duration after which the content is considered completed and the bookmark is deleted. |
thresholdPlaybackPositionMs | number | No | - | Playback position, in milliseconds, after which the content is considered completed. When set, thresholdPercentage is ignored. |
minWatchedPositionMs | number | No | - | Playback position, in milliseconds, the playhead must reach before any bookmark is written or deleted. See Minimum watched position. |
Minimum watched position
By default, bookmarks are written from the first sync. Set minWatchedPositionMs to avoid bookmarking short or accidental sessions, for example to keep a brief session from overwriting an existing Continue Watching entry.
const bookmarksConfiguration = {
endPointUrl: endpoint,
syncIntervalMS: 5000,
thresholdPercentage: 0.95,
minWatchedPositionMs: 60000, // no bookmark put or delete before 1 minute
};
- No bookmark is put or deleted until the playhead reaches
minWatchedPositionMs. Reaching it by scrubbing counts. - Once reached, the gate stays open for the rest of the session, so scrubbing back below the position still updates the bookmark.
- Completion is unchanged and still uses
thresholdPercentageorthresholdPlaybackPositionMs. To complete the content at an offset from the end, computethresholdPercentage = (duration - offset) / durationin your app. - When
minWatchedPositionMsis not set, bookmark behavior is unchanged.
Series / Episode Content
const playbackSessionBookmarker = createPlaybackSessionBookmarkerImpl(
seriesId, // contentId
bookmarkConfiguration,
platformAuthorizer,
seasonId,
episodeId,
Mode.SERIES, // Required mode based on series/episode content
undefined, // videoId (not required for series)
seasonNumber,
episodeNumber,
nextEpisodeDetails,
contentType,
logger,
);
Playlist Content
const playbackSessionBookmarker = createPlaybackSessionBookmarkerImpl(
playlistId, // contentId
bookmarkConfiguration,
platformAuthorizer,
undefined,
undefined,
Mode.PLAYLIST, // Required mode for playlist
videoId, // Required for playlist
undefined,
undefined,
undefined,
undefined,
logger,
);
Bookmark Content Handling
The PlaybackSessionBookmarker provides methods to process bookmarking at different stages of playback.
You may:
-
Manually invoke bookmarking methods during playback
-
Or integrate with
ComposablePlayerto automate bookmarking
Using with ComposablePlayer
composablePlayer.addStateChangeStep(
playbackSessionBookmarker.processPlayerStateChange,
);
Bookmark APIs
The following APIs are exposed via BookmarkService.
QueryParams
The following query parameters can be provided via the options?: QueryParams argument for list-style bookmark APIs such as getBookmarks, getSeriesBookmarks, and getPlaylistBookmarks.
| Parameter | Type | Required | Description |
|---|---|---|---|
| pageNumber | number | No | Indicate the page to retrieve. |
| pageSize | number | No | Indicate the number of records to return in response. |
| sortBy | SortBy | No | Specifies that the records to be sorted. Allowed values: timestamp. |
| sortOrder | SortOrder | No | Specifies that the records to be ordered. Allowed values: asc or desc. |
| id | string | No | Cache-busting ID added to the request URL to prevent receiving cached response. |
| includeWatchHistory | boolean | No | Include watch history in the response when true. |
Example
const options: QueryParams = {
pageNumber: 0,
pageSize: 20,
sortBy: 'timestamp',
sortOrder: 'desc',
includeWatchHistory: true,
};
getBookmark
Fetches a single bookmark record for a given content ID.
Typical use cases:
- Resume playback for a specific movie or episode
- Check whether a bookmark exists before showing a Resume button
- Restore last playback position
getBookmark(contentId: string): Promise<BookmarkRecord>
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| contentId | string | Yes | Unique identifier of the content |
getBookmarks
Retrieves a paginated list of all bookmarks for the authenticated user.
Typical use cases:
- Continue Watching rails
- Bookmark listing screens
- Dashboard resume sections
- Filtering and sorting bookmarks
Supports pagination and sorting.
getBookmarks(options?: QueryParams):Promise<BookmarkRecord[]>
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| options | QueryParams | No | Options object containing filters, pagination, and sorting |
getSeriesBookmarks
Retrieves bookmarks for all episodes under a specific series.
Typical use cases:
- Display resume positions on a series detail page
- Show episode-level bookmarks
- Fetch bookmarks specific to a TV show
Supports pagination, sorting, and optional watch history inclusion.
getSeriesBookmarks(
seriesIdentifier: string,
options?: QueryParams
): Promise<BookmarkRecord[]>
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| seriesIdentifier | string | Yes | Unique identifier of the series |
| options | QueryParams | No | Options object containing filters, pagination, and sorting |
getBookmarkCount
Retrieves the total number of bookmarks saved by the authenticated user.
Typical use cases:
- Display bookmark counters in user profiles
- Show total resume items
- Analytics or dashboard summary
getBookmarkCount(): Promise<BookmarkCount>
getPlaylistBookmarks
Retrieves the last watched positions of videos within a specific playlist.
The response returns a list of BookmarkRecord objects that identify the bookmark position for each video inside the playlist.
getPlaylistBookmarks(playlistId: string, options?: QueryParams): Promise<BookmarkRecord[]>
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| playlistId | string | Yes | Unique identifier of the playlist |
| options | QueryParams | No | Options object containing filters, pagination, and sorting |
Example
const playlistId = '123-456-7890'; // unique identifier of the playlist
bookmarkService
.getPlaylistBookmarks(playlistId)
.then((playlistBookmarks) => {
playlistBookmarks.forEach((record) => {
const contentId = record.contentId; // unique playlist ID
const videoId = record.videoId; // unique video ID within playlist
const bookmarkPosition = record.offset; // last watched position in milliseconds
const timestamp = record.timeStamp; // bookmark recorded time
});
})
.catch((error) => {
console.error('getPlaylistBookmarks failed with error', error);
});