-
Notifications
You must be signed in to change notification settings - Fork 978
Developer Guide: Collecting Video and Ad Play Statistics
This guide provides developers with detailed instructions for accurately collecting and sending video and ad play statistics to AVideo. These statistics are crucial for generating reliable reports on user interactions and ad performance.
Note: If you are developing a custom application using our API, it is essential to implement these statistics tracking methods to ensure accurate reporting. On the AVideo platform, these events and statistics are already implemented, so following these guidelines ensures consistency and completeness in your custom app.
AVideo tracks:
- Video Play Statistics: Monitors when videos start, end, and logs viewing duration. Requests should be sent every 30 seconds while the video is playing to log progress.
- Ad Play Statistics: Captures events and interactions with ads for detailed reporting.
For video tracking, developers must capture:
- Play Event: When the video starts.
- End Event: When the video finishes.
-
Progress Tracking: Send a request every 30 seconds when the video is playing to log the current playback position (
currentTime
) and accumulated play duration (seconds_watching_video
).
The seek action should not be treated as a distinct event but should be incorporated as part of the regular progress tracking process, along with the play and end events.
URL: {webSiteRootURL}/objects/videoAddViewCount.json.php
Parameter | Description | Required | Example |
---|---|---|---|
id |
The unique ID of the video being watched. | Yes | 4416 |
currentTime |
The current position in the video (in seconds). | Yes | 120 |
seconds_watching_video |
Duration watched since the last log (in seconds). | Yes | 30 |
PHPSESSID |
The PHP session ID, identifying the user's session. | Yes | ea0ga3uh3ej0hdlplbs706nva3 |
user |
The username for authentication. | No | username |
pass |
The password or token for authentication. | No | userpassword |
1. Initial Play Event When the video starts:
POST {webSiteRootURL}/objects/videoAddViewCount.json.php
{
"id": "4416",
"currentTime": "0",
"seconds_watching_video": "0",
"PHPSESSID": "ea0ga3uh3ej0hdlplbs706nva3",
"user": "username",
"pass": "userpassword"
}
2. Progress Tracking (Every 30 Seconds) While the video is playing:
POST {webSiteRootURL}/objects/videoAddViewCount.json.php
{
"id": "4416",
"currentTime": "120",
"seconds_watching_video": "30",
"PHPSESSID": "ea0ga3uh3ej0hdlplbs706nva3",
"user": "username",
"pass": "userpassword"
}
3. End Event When the video ends:
POST {webSiteRootURL}/objects/videoAddViewCount.json.php
{
"id": "4416",
"currentTime": "600",
"seconds_watching_video": "600",
"PHPSESSID": "ea0ga3uh3ej0hdlplbs706nva3",
"user": "username",
"pass": "userpassword"
}
- seconds_watching_video should only increment while the video is playing. If the video is paused or stopped, this value should not increase.
- If the
user
andpass
parameters are not provided, the system will still log the event, but the user who watched the video will not be identifiable.
URL: {webSiteRootURL}/plugin/AD_Server/log.php
Parameter | Description | Required | Example |
---|---|---|---|
label |
The type of ad event (e.g., AdStarted , AdMidpoint ). |
Yes | AdStarted |
videos_id |
The ID of the video associated with the ad. | Yes | 4416 |
video_position |
The timestamp in the video when the ad event occurred. | Yes | 0.00 |
user |
The username for authentication. | No | username |
pass |
The password or token for authentication. | No | userpassword |
POST {webSiteRootURL}/plugin/AD_Server/log.php
{
"label": "AdStarted",
"videos_id": "4416",
"video_position": "0.00",
"user": "username",
"pass": "userpassword"
}
Label | Description | Importance | Icon |
---|---|---|---|
AdStarted |
When an ad starts playing. | Important | ✅ |
AdFirstQuartile |
When the ad reaches 25% completion. | Important | ✅ |
AdMidpoint |
When the ad reaches 50% completion. | Important | ✅ |
AdThirdQuartile |
When the ad reaches 75% completion. | Important | ✅ |
AdCompleted |
When the ad finishes playing. | Important | ✅ |
AdSkipped |
When the ad is skipped. | Important | ✅ |
AdClicked |
When the ad is clicked by the user. | Important | ✅ |
AdPaused |
When the ad is paused. | Optional | 🟡 |
AdResumed |
When the ad resumes after a pause. | Optional | 🟡 |
AdError |
When an error occurs during ad playback. | Optional | 🟡 |
AdMuted |
When the ad is muted. | Optional | 🟡 |
AdUnmuted |
When the ad is unmuted. | Optional | 🟡 |
AdRewind |
When the ad is rewound. | Optional | 🟡 |
AdFullscreen |
When the ad is played in fullscreen mode. | Optional | 🟡 |
AdCreativeView |
When the ad creative is viewed. | Optional | 🟡 |
AdExitFullscreen |
When the ad exits fullscreen mode. | Optional | 🟡 |
AdAcceptInvitationLinear |
When an invitation to interact with a linear ad is accepted. | Optional | 🟡 |
AdCloseLinear |
When a linear ad is closed. | Optional | 🟡 |
- ✅: Important (Critical for comprehensive ad tracking)
- 🟡: Optional (Additional insights but not mandatory)
- Important events are critical for logging comprehensive ad performance metrics.
- Optional events provide additional insights but are not mandatory for basic ad tracking.
- If the
user
andpass
parameters are not provided, the system will log the event, but it will not identify the user interacting with the ad.
To track ad events on other platforms:
-
Monitor Ad Events:
- Use the native APIs provided by the platform (e.g., Google IMA SDK for mobile apps) to listen for ad events such as
AdStarted
,AdCompleted
, etc.
- Use the native APIs provided by the platform (e.g., Google IMA SDK for mobile apps) to listen for ad events such as
-
Log Events:
- Structure the data to match the AVideo API parameters (
label
,videos_id
,video_position
). - Make API calls to the endpoint (
AD_Server/log.php
) whenever a relevant ad event occurs.
- Structure the data to match the AVideo API parameters (
-
Handle Authentication:
- Ensure that the
PHPSESSID
,user
, andpass
parameters are included in the request for proper logging.
- Ensure that the
To ensure consistent behavior across all devices and platforms:
-
Mobile Apps: Implement the API calls and tracking logic using native video player APIs (e.g., AVPlayer for iOS and ExoPlayer for Android).
-
Smart TVs: Utilize SDKs specific to each platform (e.g., Roku, Amazon Fire TV) to implement tracking logic.
-
Web Players: Follow the JavaScript guidelines as detailed in the AVideo JS event tracking guide.