Explanation of Methods for Counting Video Watch Duration
Many educational scenarios require tracking how long viewers have watched a video. This is used to determine whether a course has been completed, whether to trigger the next action (such as watching the next course), or simply to display the viewer's watch duration and number of videos watched on the frontend.
Overall, there are two methods for counting watch duration: one is to obtain statistical data via the server-side API, and the other is to use the interfaces provided by the frontend player, with the business party handling the statistics themselves. The pros and cons of each method and their applicable scenarios are shown in the table below:
| Statistical Method | Frontend Statistics | Server-Side API Acquisition |
|---|---|---|
| Timeliness | Real-time | Non-real-time. There is a certain delay as the server needs to process playback data from the entire platform. |
| Data Accuracy | Accurate | Slight inaccuracies. Due to network, link, and other factors, frontend-reported playback data may fail to send, so the watch duration returned by the server cannot be guaranteed to be absolutely accurate. |
| Development Cost | High. The business party needs to use the player's relevant interfaces to calculate watch duration and other data on the frontend and report it to the business backend. | Low. Only need to call the corresponding API to obtain statistical results. |
| Applicable Scenarios | Business scenarios with high real-time requirements for statistics | Business scenarios with low real-time requirements for statistics |
Introduction to Frontend Statistics Method
Web Player (including PC H5, Flash, Mobile H5 Player)
When playing a video on a web page, you can use the relevant interfaces and events provided by the player, combined with your own business rules, to count the required data and report it to your own business system.
Interfaces:
j2s_getCurrentTime()// Gets the current playback time point. For example, if the video plays to the 20th second, it returns: 20.j2s_realPlayVideoTime()// Gets the main content playback time, excluding ads, intros, pauses, credits, etc. This value accumulates during video playback.
Events:
s2j_onPlayStart// Triggered when the player successfully loads the video file and buffering is complete, just before playback starts.s2j_onPlayOver// Triggered after playback ends.
For other player properties, interfaces, and events, see Properties and Interface Description.
Note:
j2s_realPlayVideoTimegets the natural time duration of playback. For example, when playing at 2x speed to the 60th second of the video:player.j2s_getCurrentTime() = 60player.j2s_realPlayVideoTime() = 30
Mobile SDK (Android SDK, iOS SDK)
When playing a video in an app, you can use the relevant interfaces and events provided by the POLYV VOD SDK, combined with your own business rules, to count the required data and report it to your own business system.
iOS SDK:
@property (nonatomic, assign, readonly) NSTimeInterval viewerWatchDuration// User watch time. If playing at 2x speed to the 60th second of the video, this method returns 30.@property (nonatomic, assign, readonly) NSTimeInterval videoContentPlayedTime// Video content playback time. If playing at 2x speed to the 60th second of the video, this method returns 60.
Android SDK:
getWatchTimeDuration()// User watch time. If playing at 2x speed to the 60th second of the video, this method returns 30.getVideoContentPlayedTime()// Video content playback time. If playing at 2x speed to the 60th second of the video, this method returns 60.
The SDKs also have event callbacks for playback start, completion, errors, etc. For other player properties, interfaces, and events, see the GitHub documentation: iOS, Android.
Introduction to Server-Side API Acquisition Method
Via Watch Logs:
- Get video watch logs for a specific day API
- Batch get video watch logs API
- Or via VOD Backend → Data Statistics → Watch Logs, you can view and export data such as video ID, viewer ID, watch duration, etc.
Via Video Completion API:
API Documentation: Get Video Watch Completion API
This API allows you to check the cumulative completion status of a specific viewer for a specific video. Regardless of which terminal the viewer uses or how many times they watch, the API returns the final aggregated completion percentage.
For example, video A has a duration of 50 minutes. A viewer watches minutes 020 on a PC H5, minutes 1030 on a mobile H5, and minutes 4050 on an app. The cumulative watch duration is 20+20+10=50 minutes, but the video content watched is minutes 030 and 40~50. Although the cumulative watch duration equals the video duration, the completion percentage is (30+10)/50=80%.
Via Video Advanced Analytics:
Feature Documentation: Advanced Analytics Feature Description
API Documentation: Advanced Analytics - Paginated Query of Watch Behavior List
Note:
- Data obtained via the watch log API typically has a delay of 10 minutes under normal circumstances.
- The start time in the exported Excel sheet from the backend is the time the data was stored, not the time the video started playing.
- Video watch completion is calculated once every hour on the server side, meaning there is a maximum delay of 1 hour.
- Advanced analytics are calculated once a day, meaning there is a maximum delay of 24 hours.
- The completion percentage from the completion API and advanced analytics is calculated based on normal video speed. For example, if a video is watched completely at 2x speed, the completion percentage will be calculated as 50%.
