Skip to main content

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​

PropertyTypeRequiredDefaultDescription
syncIntervalMSnumberNo5000Interval, in milliseconds, at which the bookmark is synced.
thresholdPercentagenumberNo0.95Fraction of the content duration after which the content is considered completed and the bookmark is deleted.
thresholdPlaybackPositionMsnumberNo-Playback position, in milliseconds, after which the content is considered completed. When set, thresholdPercentage is ignored.
minWatchedPositionMsnumberNo-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 thresholdPercentage or thresholdPlaybackPositionMs. To complete the content at an offset from the end, compute thresholdPercentage = (duration - offset) / duration in your app.
  • When minWatchedPositionMs is 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 ComposablePlayer to 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.

ParameterTypeRequiredDescription
pageNumbernumberNoIndicate the page to retrieve.
pageSizenumberNoIndicate the number of records to return in response.
sortBySortByNoSpecifies that the records to be sorted. Allowed values: timestamp.
sortOrderSortOrderNoSpecifies that the records to be ordered. Allowed values: asc or desc.
idstringNoCache-busting ID added to the request URL to prevent receiving cached response.
includeWatchHistorybooleanNoInclude 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

ParameterTypeRequiredDescription
contentIdstringYesUnique 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

ParameterTypeRequiredDescription
optionsQueryParamsNoOptions 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

ParameterTypeRequiredDescription
seriesIdentifierstringYesUnique identifier of the series
optionsQueryParamsNoOptions 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

ParameterTypeRequiredDescription
playlistIdstringYesUnique identifier of the playlist
optionsQueryParamsNoOptions 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);
});