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,
);

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.

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);
  });