Cloud Bookmarks

The bookmarks library is a personalization library that provides bookmarking service for Continue Watching feature. The library facilitates bookmarking any content at different stages of playback and also provides API to retrieve the bookmarked offset time to start playback from last watched position.

The BookmarkService is the interface for bookmarking contract which has all the APIs to perform different bookmarking operations (Put, Delete & Get bookmark records). The BookmarksManager is composed on bookmark service to manage bookmarking with Player and ComposablePlayer.

Bookmark Configuration

import { createPlayer, PlayerConfig, BookmarkerConfig } from '@quickplay/rn-qp-nxg-player';

const bookmarkConfig: BookmarkerConfig = {
    bookmarkServiceEndpoint: "https://bookmark-service.example.com",
    bookmarkAssetID: "playlist-12345",  // The playlist identifier
    videoId: "video-67890",             // The individual asset/video ID within playlist
    bookmarkSyncIntervalMs: 10000,
    bookmarkDeleteThreshold: 0.9,
    thresholdPlaybackPositionMs: 60000,                   // Enable playlist mode
}

let playerConfig: PlayerConfig = { 
    ...
    bookmarkConfig: bookmarkConfig
    ...
}

let player = await createPlayer(playerConfig)

Playlist Bookmarks

The player supports playlist-level bookmarking, allowing you to track playback progress across multiple assets within a playlist or series.

Playlist Bookmark Configuration

To enable playlist bookmarking, configure the bookmark settings with mode: 'PLAYLIST':

import { createPlayer, PlayerConfig, BookmarkerConfig } from '@quickplay/rn-qp-nxg-player';

const bookmarkConfig: BookmarkerConfig = {
    bookmarkServiceEndpoint: "https://bookmark-service.example.com",
    bookmarkAssetID: "playlist-12345",  // The playlist identifier
    videoId: "video-67890",             // The individual asset/video ID within playlist
    bookmarkSyncIntervalMs: 10000,
    bookmarkDeleteThreshold: 0.9,
    thresholdPlaybackPositionMs: 60000,
    mode: 'PLAYLIST',                   // Enable playlist mode
}

let playerConfig: PlayerConfig = { 
    ...
    bookmarkConfig: bookmarkConfig
    ...
}

let player = await createPlayer(playerConfig)

Parameter	Type	Description
bookmarkAssetID	String	The playlist identifier (parent level)
videoId	String	The individual video/asset identifier within the playlist
mode	String	Set to 'PLAYLIST' for playlist bookmarking

Note: When using playlist bookmarking:

• bookmarkAssetID identifies the playlist container
• videoId tracks the specific asset being played within that playlist
• This allows the player to resume from the correct asset when returning to a playlist

Initializing Bookmark Service

Before using any bookmark retrieval methods (getBookmark, getBookmarks, getPlaylistBookmarks, getSeriesBookmarks), you must initialize the bookmark service:

import { bookmarkService } from '@quickplay/rn-qp-nxg-player';

const bookmarkConfig = {
    bookmarkServiceEndpoint: "https://bookmark-service.example.com"
};

try {
    await bookmarkService.initializeBookmarkService(bookmarkConfig);
    console.log('Bookmark service initialized successfully');
} catch (error) {
    console.error('Failed to initialize bookmark service:', error);
}

Important: This initialization step is required before calling any bookmark retrieval methods.

Retrieving a Single Bookmark

Use the getBookmark API to retrieve a bookmark record for a specific asset:

import { bookmarkService, BookmarkRecord } from '@quickplay/rn-qp-nxg-player';

// Initialize bookmark service first (shown above)
await bookmarkService.initializeBookmarkService(bookmarkConfig);

try {
    const bookmark: BookmarkRecord = await bookmarkService.getBookmark('asset-id-12345');
    
    console.log('Bookmark offset (ms):', bookmark.offset);
    console.log('Last updated:', bookmark.updatedTimestamp);
    
    // Use the bookmark offset to resume playback
    const resumePosition = bookmark.offset / 1000; // Convert to seconds
} catch (error) {
    console.log('No bookmark found for this asset');
}

Retrieving All Bookmarks

Use the getBookmarks API to retrieve all bookmark records:

import { bookmarkService, BookmarkRecord } from '@quickplay/rn-qp-nxg-player';

// Initialize bookmark service first
await bookmarkService.initializeBookmarkService(bookmarkConfig);

try {
    const bookmarks: BookmarkRecord[] = await bookmarkService.getBookmarks();
    
    console.log(`Found ${bookmarks.length} bookmarks`);
    bookmarks.forEach(bookmark => {
        console.log(`Asset: ${bookmark.itemId}, Offset: ${bookmark.offset}ms`);
    });
} catch (error) {
    console.error('Failed to fetch bookmarks:', error);
}

Retrieving Playlist Bookmarks

Use the getPlaylistBookmarks API to retrieve all bookmark records for a specific playlist:

import { bookmarkService, BookmarkParams, BookmarkRecord } from '@quickplay/rn-qp-nxg-player';

// Initialize bookmark service first
const bookmarkConfig = {
    bookmarkServiceEndpoint: "https://bookmark-service.example.com"
};
await bookmarkService.initializeBookmarkService(bookmarkConfig);

const bookmarkParams: BookmarkParams = {
    pageNumber: 1,           // Optional
    pageSize: 10,            // Optional
    sortBy: 'timestamp',     // Optional
    sortOrder: 'desc'        // Optional
};

try {
    const playlistBookmarks: BookmarkRecord[] = await bookmarkService.getPlaylistBookmarks(
        'playlist-12345',     // playlistIdentifier
        bookmarkParams
    );
    
    console.log('Playlist bookmarks:', playlistBookmarks);
    // Process the bookmarks - each record contains offset, videoId, timestamp, etc.
} catch (error) {
    console.error('Failed to fetch playlist bookmarks:', error);
}

Retrieving Series Bookmarks

Similar to playlist bookmarks, use the getSeriesBookmarks API to retrieve all bookmark records for a series:

import { bookmarkService, BookmarkParams, BookmarkRecord } from '@quickplay/rn-qp-nxg-player';

// Initialize bookmark service first
const bookmarkConfig = {
    bookmarkServiceEndpoint: "https://bookmark-service.example.com"
};
await bookmarkService.initializeBookmarkService(bookmarkConfig);

const bookmarkParams: BookmarkParams = {
    pageNumber: 1,
    pageSize: 10,
    sortBy: 'timestamp',
    sortOrder: 'desc'
};

try {
    const seriesBookmarks: BookmarkRecord[] = await bookmarkService.getSeriesBookmarks(
        'series-98765',       // seriesIdentifier
        bookmarkParams
    );
    
    console.log('Series bookmarks:', seriesBookmarks);
    // Each bookmark contains episode-specific playback position
} catch (error) {
    console.error('Failed to fetch series bookmarks:', error);
}

BookmarkParams

Parameter	Type	Required	Default	Description
pageNumber	Number	No	1	Page number for pagination
pageSize	Number	No	10	Number of records per page
sortBy	String	No	timestamp	Sort field ('timestamp')
sortOrder	String	No	desc	Sort order ('asc' or 'desc')