Developer Guide: Collecting Video and Ad Play Statistics

I understand. Below is an updated version that provides guidance for developers to build similar functionality for collecting video and ad play statistics on their apps, based on the AVideo model. This guide focuses on the structure and logic required so developers can adapt the solution to different environments such as mobile apps or Smart TVs.

AVideo Developer Guide: Collecting Video and Ad Play Statistics

This guide provides developers with instructions for accurately collecting and sending video and ad play statistics to AVideo, helping generate reliable reports on user interactions and ad performance.

📊 Overview

AVideo tracks:

• Video Play Statistics: Monitors when videos start and 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.

---

1. Video Play Statistics 🎥

Tracking Requirements

For video tracking, developers must capture two key events:

• Play Event: When the video starts.
• End Event: When the video finishes.

Additionally, while the video is playing, a request should be sent every 30 seconds to log the current progress. The logged seconds_watching_video should only count if the video is actively playing; if paused or stopped, it should not accumulate.

Endpoint

URL: {webSiteRootURL}/objects/videoAddViewCount.json.php

Parameters

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

Example API Call

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"
}

Implementation Guide for Other Platforms (Mobile Apps, Smart TVs)

To build a similar feature for mobile apps or Smart TVs:

1. Set Up Tracking:

   • Use native APIs to monitor the play state of the video (e.g., AVPlayer for iOS, ExoPlayer for Android, or specific SDKs for Smart TVs).
   • Track events like play, pause, seek, and end using platform-specific event listeners.

2. Create a Timer for Interval Tracking:

   • Use a timer that runs every 30 seconds to log the video’s current position and the duration watched (seconds_watching_video).
   • Make sure the timer increments seconds_watching_video only if the video is actively playing.

3. Structure the API Call:

   • On each interval, send an HTTP POST request to the AVideo endpoint (videoAddViewCount.json.php), passing the video ID, current time, and watching duration.
   • Ensure that the user’s session ID (PHPSESSID), user, and pass parameters are included for authentication.

Important Implementation Notes 📝

• If the user and pass parameters are not provided, the system will still log the event, but it will not identify the user who watched the video.

---

2. Ad Play Statistics 🛑

Endpoint

URL: {webSiteRootURL}/plugin/AD_Server/log.php

Parameters

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

Example API Call

POST {webSiteRootURL}/plugin/AD_Server/log.php
{
    "label": "AdStarted",
    "videos_id": "4416",
    "video_position": "0.00",
    "user": "username",
    "pass": "userpassword"
}

Ad Event Labels

Label	Description	Importance
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
AdPaused	When the ad is paused.	Optional
AdResumed	When the ad resumes after a pause.	Optional
AdSkipped	When the ad is skipped.	Optional
AdClicked	When the ad is clicked by the user.	Optional
AdError	When an error occurs during ad playback.	Important

Implementation Guide for Other Platforms

To track ad events on different platforms:

1. Monitor Ad Events:

   • Use ad-specific APIs provided by the platform (e.g., Google IMA SDK for mobile apps) to listen for ad events like AdStarted, AdCompleted, etc.

2. 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.

3. Handle Authentication:

   • Ensure that the PHPSESSID, user, and pass parameters are included in the request for proper logging.

Important Implementation Notes 📝

• If user and pass are not provided, the system logs the event but does not identify the user who interacted with the ad.

---

📱 Cross-Platform Implementation

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.