Continue Watching

The Continue Watching feature allows users to resume videos from where they left off. It tracks viewing progress per user and provides methods to retrieve and check watch states.

Setting User ID

The player generates a user ID automatically, however it can be overridden using the setUserId method as shown below.

Basic Usage

Set a user ID for the current player instance only:

const player = vpPlayer("vp-player");
player.setup(config).then(() => {
    player.setUserId("user-1234567890");
});

Persistent User ID (localStorage)

To save the user ID in localStorage and automatically use it for all future player instances on the same device, pass true as the second parameter:

const player = vpPlayer("vp-player");
player.setup(config).then(() => {
    player.setUserId("user-abcdefghijklmnop", true);
});

When save is set to true, the user ID is stored in localStorage under the key vpUserId. The next time the user visits your site, this ID will be automatically loaded for all player instances.

note

• The user ID must be a non-empty string.
• If localStorage is not available (e.g., in private browsing mode), saving will fail and the user ID will be used for that instance only.

Configuration

Enable the continue watching UI elements in the player setup configuration:

const config = {
    // ... other config
    config: {
        showContinueWatching: true,
        // ... other config options
    },
};

The showContinueWatching property controls whether the continue watching button and related UI elements are displayed in the player. See the Full Configuration reference for all available options.

Automatic Behavior

Continue watching is automatically initialized when:

1. A valid userId is set on the player
2. A video is loaded with a valid videoId
3. The user watches content (progress is saved automatically)

The player automatically:

• Fetches the last watched position when a video loads
• Saves watch progress periodically during playback
• Marks videos as "watched" when viewed beyond 90% of their duration

Public Methods

getWatchTimes(userId, assetId)

Retrieves watch time information for a user and optionally a specific video.

Parameters:

• userId (string, optional) — User ID to query. Defaults to the current player's userId.
• assetId (string, optional) — Specific video/asset ID to query. If omitted, returns all watch times for the user.

Returns:

• If assetId is provided: Promise<number> — The watch time position in seconds (or 0 if not found)
• If assetId is omitted: Promise<Asset[]> — Array of all watched assets with their positions

// Asset object structure
{
    assetId: "video-123",
    position: "45.6" // seconds as string
}

Example:

const player = vpPlayer("vp-player");
player.setup(config).then(async () => {
    player.setUserId("user-123");

    // Get all watched videos for this user
    const allWatchedVideos = await player.getWatchTimes();

    // Get watch time for a specific video
    const watchTime = await player.getWatchTimes("user-123", "video-1");
});

hasBeenWatched(assetDuration)

Checks if the current video has been watched beyond the threshold (90% by default).

Parameters:

• assetDuration (number, optional) — The total duration of the video in seconds. If not provided, uses the current video's duration.

Returns:

• boolean — true if the user has watched more than 90% of the video, false otherwise.

Example:

const player = vpPlayer("vp-player");
player.setup(config).then(() => {
    player.setUserId("user-123");

    player.on("ready", () => {
        if (player.hasBeenWatched()) {
            console.log("User has already watched this video");
        }
    });
});

Complete Example

const player = vpPlayer("vp-player");

player.setup(config).then(async () => {
    // Set user ID and save it for future sessions
    player.setUserId("user-abc123", true);

    // Check if this video has been watched before
    const isWatched = player.hasBeenWatched();
    if (isWatched) {
        console.log("User has completed this video");
    }

    // Get all watched videos for this user
    const allWatchedVideos = await player.getWatchTimes();
    console.log(`User has watched ${allWatchedVideos.length} videos`);

    // Get watch time for current video
    const currentVideoWatchTime = await player.getWatchTimes("user-abc123", config.video.videoId);
    if (currentVideoWatchTime > 0) {
        console.log(`User previously watched up to ${currentVideoWatchTime} seconds`);
    }
});

note

The userId and videoId values set on the player are the same identifiers used by the Playback Position API endpoints. You can use these endpoints to retrieve watch progress outside of the player context, for example to display watched duration overlays on video grid cards.