Developer Guide Collecting Video and Ad Play Statistics

This guide is for developers who build their own player or app (mobile, smart TV, custom web player) on top of an AVideo site. It explains which requests to send so that video views, watch time and ad events appear in the AVideo reports.

Note: The AVideo website player already sends all of these requests. You only need this guide for your own player or app.

Quick Links

• Video Play Statistics
• Ad Play Statistics

---

Overview

AVideo records:

• Video play statistics: views, the current position and the time watched. They feed the view counter, the watch-time reports and plugins such as VideosStatistics and MonetizeUsers.
• Ad play statistics: ad events (started, completed, skipped, clicked...). They feed the Video Ad Events Report.

In the examples, replace your-site.com with your site address.

---

1. Video Play Statistics

When to send a request

Send a request:

• when the video starts playing,
• when it is paused,
• when it ends,
• every 30 seconds while it plays.

A seek is not a separate event: the next request simply carries the new position.

Endpoint

https://your-site.com/objects/videoAddViewCount.json.php

Method: POST, with normal form fields (application/x-www-form-urlencoded), not JSON.

Parameters

Parameter	Where	Description	Required	Example
id	POST field	The video ID	Yes	4416
currentTime	POST field	Current position in the video, in seconds	Yes	120
seconds_watching_video	POST field	Seconds actually watched since the previous request (do not count paused time)	Yes	30
PHPSESSID	URL query string	The viewer's session ID (see below)	Recommended	ea0ga3uh3ej0hdlplbs706nva3
user, pass	POST field	Username and password, so the view is linked to that user	No

Session and cookies

• The request must carry the site's session cookie. Without it the answer is "msg": "Cookie is disabled" and nothing is recorded. Use a cookie jar: open any page of the site once (for example the video page), then send the statistics requests with the same cookies. Apps whose User-Agent contains AVideoMobileApp skip this check.
• PHPSESSID is read only from the URL query string, not from the POST body. The JSON answer returns the current session_id; keep using it.
• One view is counted per video per session. Later requests in the same session only update the position and watch time.
• Without user/pass (or a logged-in session), the view is recorded but not linked to a user.
• Bots are ignored, and each client is limited to 240 requests per minute.

Example

curl -c cookies.txt -b cookies.txt \
  -d "id=4416" -d "currentTime=120" -d "seconds_watching_video=30" \
  "https://your-site.com/objects/videoAddViewCount.json.php?PHPSESSID=ea0ga3uh3ej0hdlplbs706nva3"

For the first request use currentTime=0 and seconds_watching_video=0. When the video ends, send the final position and the seconds watched since the last request.

---

2. Ad Play Statistics

Endpoint

https://your-site.com/plugin/AD_Server/log.php

Method: POST (form fields). The events are stored in the tables of the AD_Server plugin, so AD_Server must have its tables installed (Admin Panel → Plugins → AD_Server → Install tables).

Parameters

Parameter	Description	Required	Example
label	The ad event name (see the list below)	Yes	AdStarted
videos_id	The ID of the video the ad played on	Yes	4416
video_position	Position in the video when the event happened, in seconds	Yes	0
campaign_has_videos_id	Only for AD_Server ads: the campaign video ID. Events with it count as "Own Videos" in the report, events without it as "Third Party Ads".	No	12
user, pass	Username and password, so the event is linked to that user	No

Requests sent with the HTTP Origin header https://imasdk.googleapis.com are ignored.

Example

curl -b cookies.txt \
  -d "label=AdStarted" -d "videos_id=4416" -d "video_position=0" \
  "https://your-site.com/plugin/AD_Server/log.php"

Ad Event Labels

Label	When to send it	Importance
AdStarted	The ad starts playing	Important
AdFirstQuartile	25% of the ad was played	Important
AdMidpoint	50% of the ad was played	Important
AdThirdQuartile	75% of the ad was played	Important
AdCompleted	The ad finished	Important
AdSkipped	The viewer skipped the ad	Important
AdClicked	The viewer clicked the ad	Important
AdPaused	The ad was paused	Optional
AdResumed	The ad resumed after a pause	Optional
AdError	The ad could not play	Optional
AdMuted / AdUnmuted	The ad was muted / unmuted	Optional
AdRewind	The ad was rewound	Optional
AdFullscreen / AdExitFullscreen	Fullscreen was entered / exited during the ad	Optional
AdCreativeView	The ad creative was shown	Optional
AdAcceptInvitationLinear	The viewer accepted a linear ad invitation	Optional
AdCloseLinear	A linear ad was closed	Optional

Use exactly these names (they are case-sensitive): the report groups events by this text.

Implementation guide for other platforms (mobile apps, smart TVs)

1. Listen to the ad events of your ad SDK (for example the Google IMA SDK for Android or iOS).
2. Map each event to one of the labels above.
3. Send one request to log.php for each event, with label, videos_id and video_position.

To get the ads themselves in an app, request the VMAP of a video through the API: https://your-site.com/plugin/API/get.json.php?APIName=vmap&videos_id=4416. See Different ad tags to serve different ads per app.

---

Cross-Platform Implementation

• Mobile apps: use the native player events (for example AVPlayer on iOS, ExoPlayer on Android) to know when to send the requests.
• Smart TVs: use the player events of each platform SDK (Roku, Amazon Fire TV...).
• Web players: see how the AVideo player does it in playerAdsEvents.js (ad events) and addView.js (views).