Skip to content

Developer Guide: Collecting Video and Ad Play Statistics

Daniel Neto edited this page Oct 25, 2024 · 8 revisions

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.

📌 Quick Links


📊 Overview

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.

1. Video Play Statistics 🎥

Tracking Requirements

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.

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

Important Implementation Notes 📝

  • 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 and pass parameters are not provided, the system will still log the event, but the user who watched the video will not be identifiable.

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 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 🟡

Icon Legend

  • : Important (Critical for comprehensive ad tracking)
  • 🟡: Optional (Additional insights but not mandatory)

Notes:

  • 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 and pass parameters are not provided, the system will log the event, but it will not identify the user interacting with the ad.

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

To track ad events on other platforms:

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

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

Clone this wiki locally