Skip to main content

Video Player Events Reference

Event Description & Availability#

The Veeplay Video Player event tracking system is designed to support two use cases:

  • Provide hooks for programmatic access to player and media lifecycle events;
  • Log all events to one or more tracking servers for analytics and audit purposes.

The available events are a superset of the official IAB VAST Tracking Events, allowing for simple VAST ad integration. Remote tracking is configured automatically for media units built using VAST or VMAP, but can also be configured programatically on each platform.

Event NameTriggeredJS SupportiOS SupportAndroid Support
LaunchWhen a media unit or overlay begins processing, even if there is no content to display.
StartWhen a video (or an individual creative within an ad) was loaded and playback began
FinishWhen a media unit or overlay finishes processing, even if there was no content to display.
Playlist FinishedWhen the current playlist finishes.
Exit FullscreenWhen the player exits fullscreen mode.
Enter FullscreenWhen the player enters fullscreen mode.
Toggle FullscreenWhen the player's fullscreen status changes.
ImpressionWhen the first frame of a video or the content of an overlay is displayed.
Viewable ImpressionWhen the content meets the criteria for a viewable video impression.
Impression Not ViewableWhen the content does not meet the criteria for a viewable video impression.
Impression With Undetermined ViewabilityWhen the criteria for a viewable video impression cannot be determined.
Creative ViewWhen an individual creative portion of an ad is viewed.
PauseWhen the video is paused.
ResumeWhen the video playback resumes after a pause.
RewindWhen the video is seeked backward.
ForwardWhen the video is seeked forward.
MuteWhen the player is muted.
UnmuteWhen the player is unmuted.
ErrorWhen an error is encountered.
CompleteWhen a video is played until the end, or an overlay is displayed for the entire scheduled duration.
CloseWhen a video is stopped or an overlay is closed by the user.
Video CloseWhen a video is stopped by the user.
SkipWhen a video is skipped (via the skip overlay)..
ClickWhen an ad is clicked (via the button overlay).
Icon ViewWhen an industry icon is displayed.
Ad ExpandWhen a MRAID ad is expanded.
Ad CollapseWhen a MRAID ad is collapsed.
PositionOn SSAI ad progress (first quartile, midpoint, third quartile).
SeekedAfter video was seeked.
SSAI Ad StartedWhen a SSAI ad starts.
SSAI Ad EndedWhen a SSAI ad ends.
Ad Break StartedWhen an ad break starts processing.
Ad RequestedWhen a VAST tag is requested from the network.
Ad Request CompleteWhen a VAST tag has finished retrieving from the network.
Ad Request ErrorWhen an error appeared during retrieving a VAST tag from the network.
Ad Break EmptyWhen a retrieved VAST tag did not contain an ad
Unit FinishedWhen a media unit finishes processing.
Invalid LicenseWhen there is an issue with the player commercial license.
Playback Status ChangeWhen the player playback status changes.
Load State ChangeWhen a video load state changes.
Unit StartedWhen a media unit starts processing.
Playback RequestedWhen video content is requested from the network.
Player TappedWhen the player surface is clicked/tapped.
Controls DisplayedWhen the video controls are displayed.
Controls HiddenWhen the video controls are hidden.
UpdateEvery seconds, while the player is running.
Event TrackedWhen an event was tracked to a remote server.
Will Open BrowserWhen the user clicks on an ad, triggering an in-app browser to open.
Will Close BrowserWhen the user closes the in-app browser.
Duration AvailableWhen the duration of the current video is available.
Volume ChangedWhen the audio volume changes.
Mouse MoveWhen the mouse is moved on top of the video player surface.

JavaScript SDK Event Support#

Subscribing to Notifications and Events#

If you've installed Veeplay using NPM, import the notifications and events from the main entrypoint:

import { MediaPlayer, NOTIFICATIONS, EVENTS } from 'veeplay'

If you've installed Veeplay using the CDN links, NOTIFICATIONS and EVENTS will be globally available.

The player uses an EventEmitter instance for propagating player events. The instance is unique per each player object and can be accessed using the following method:

const tracker = player.getEventTracker()

In order to subscribe to notifications, use the event emitter:

tracker.emitter.on(
NOTIFICATIONS.ENTER_FULLSCREEN,
() => console.log('fullscreen mode on'),
);

In order to hook into events, subscribe to the trackedEvent notification and read the attached event:

tracker.emitter.on('trackedEvent', (e) => {
if (e.event === EVENTS.PAUSE) {
console.log('paused');
} else if (e.event === EVENTS.RESUME) {
console.log('resumed');
}
});

See the full documentation on notifications and events.

Event and Notification Names#

Event NameEventNotification
LaunchLAUNCH
StartSTART
FinishFINISH
Playlist FinishedPLAYLIST_FINISH
Exit FullscreenEXIT_FULLSCREENEXIT_FULLSCREEN
Enter FullscreenFULLSCREENENTER_FULLSCREEN
Toggle FullscreenTOGGLE_FULLSCREEN
ImpressionIMPRESSION
Viewable Impression
Impression Not Viewable
Impression With Undetermined Viewability
Creative ViewCREATIVE_VIEW
PausePAUSE
ResumeRESUME
RewindREWIND
ForwardFORWARD
MuteMUTE
UnmuteUNMUTE
ErrorERRORERROR
CompleteCOMPLETE
CloseCLOSE
Video CloseCLOSE_LINEAR
SkipSKIP
ClickCLICK
Icon ViewICON_VIEW
Ad Expand
Ad Collapse
PositionPOSITION
SeekedSEEKED
SSAI Ad StartedSSAI_AD_STARTED
SSAI Ad EndedSSAI_AD_ENDED
Ad Break Started
Ad Requested
Unit FinishedUNIT_FINISHED
Invalid LicenseINVALID_LICENSE
Playback Status ChangePLAYBACK_STATE_CHANGED
Load State ChangeLOAD_STATE_CHANGED
Unit Started
Playback Requested
Player TappedPLAYER_TAPPED
Controls DisplayedCONTROLS_DISPLAYED
Controls HiddenCONTROLS_HIDDEN
UpdateUPDATEPLAYER_UPDATE
Event TrackedTRACKED_EVENT
Will Open Browser
Will Close Browser
Duration AvailableDURATION_AVAILABLE
Volume ChangedVOLUME_CHANGED
Mouse MovePLAYER_MOUSE_MOVE

iOS SDK Event Support#

Subscribing to Notifications and Events#

Use the Notification Center API to subscribe to notifications:

NotificationCenter.default.addObserver(self, selector: #selector(onUnitFinished(_:)), name: Notification.Name(rawValue: APSMediaPlayerUnitFinishedNotification), object: nil)
...
@objc func onUnitFinished(_ notification: Notification) {
...
}

You subscribe to events by subscribing to the APSMediaPlayerTrackedEventNotification, and consuming the data in the userInfo dictionary:

NotificationCenter.default.addObserver(self, selector: #selector(onUnitFinished(_:)), name: Notification.Name(rawValue: APSMediaPlayerUnitFinishedNotification), object: nil)
...
@objc func onUnitFinished(_ notification: Notification) {
if let info = notification.userInfo as [String:String]? {
if let type = info[kAPSMediaPlayerEventType] as String? {
print(type)
}
}
}

Read the APSMediaPlayer class documentation for more info on subscribing to and consuming notifications.

Event and Notification Names#

Event NameEventNotification
LaunchAPSMediaPlayerEventLaunch
StartAPSMediaPlayerEventStart
FinishAPSMediaPlayerEventFinish
Playlist FinishedAPSMediaPlayerEventPlaylistFinish
Exit FullscreenAPSMediaPlayerEventExitFullscreenAPSMediaPlayerWillExitFullscreenNotification, APSMediaPlayerDidExitFullscreenNotification
Enter FullscreenAPSMediaPlayerEventFullscreenAPSMediaPlayerWillEnterFullscreenNotification, APSMediaPlayerDidEnterFullscreenNotification
Toggle FullscreenAPSMediaPlayerToggleFullscreenNotification
ImpressionAPSMediaPlayerEventImpression
Viewable ImpressionAPSMediaPlayerEventViewableImpressionViewable
Impression Not ViewableAPSMediaPlayerEventViewableImpressionNotViewable
Impression With Undetermined ViewabilityAPSMediaPlayerEventViewableImpressionUndetermined
Creative ViewAPSMediaPlayerEventCreativeView
PauseAPSMediaPlayerEventPause
ResumeAPSMediaPlayerEventResume
RewindAPSMediaPlayerEventRewind
ForwardAPSMediaPlayerEventForward
MuteAPSMediaPlayerEventMute
UnmuteAPSMediaPlayerEventUnmute
ErrorAPSMediaPlayerEventErrorAPSMediaPlayerErrorNotification
CompleteAPSMediaPlayerEventComplete
CloseAPSMediaPlayerEventClose
Video CloseAPSMediaPlayerEventCloseLinear
SkipAPSMediaPlayerEventSkip
ClickAPSMediaPlayerEventClick
Icon ViewAPSMediaPlayerEventIconView
Ad ExpandAPSMediaPlayerEventExpand
Ad CollapseAPSMediaPlayerEventCollapse
PositionAPSMediaPlayerEventPosition
SeekedAPSMediaPlayerEventSeeked
SSAI Ad StartedAPSMediaPlayerEventSSAIAdStarted
SSAI Ad EndedAPSMediaPlayerEventSSAIAdEnded
Ad Break StartedAPSMediaPlayerEventAdBreakTriggered
Ad RequestedAPSMediaPlayerEventAdRequested
Unit FinishedAPSMediaPlayerUnitFinishedNotification
Invalid LicenseAPSMediaPlayerInvalidLicenseNotification
Playback Status ChangeAPSMediaPlayerStatusChangedNotification, APSMediaPlayerPlaybackStateDidChangeNotification
Load State ChangeAPSMediaPlayerLoadStateDidChangeNotification
Unit Started
Playback Requested
Player TappedAPSMediaPlayerWasTappedNotification
Controls DisplayedAPSMediaPlayerControlsDisplayedNotification
Controls HiddenAPSMediaPlayerControlsHiddenNotification
UpdateAPSMediaPlayerEventUpdateAPSMediaPlayerUpdateNotification
Event TrackedAPSMediaPlayerTrackedEventNotification
Will Open BrowserAPSMediaPlayerWillOpenMiniBrowser
Will Close BrowserAPSMediaPlayerWillCloseMiniBrowser
Duration AvailableAPSMediaPlayerDurationAvailableNotification
Volume ChangedAPSMediaPlayerVolumeDidChangeNotification
Mouse Move

Android SDK Event Support#

Subscribing to Events#

The APSMediaEvents class defines the events that the Veeplay player emits. In order to receive events, implement the APSMediaPlayerTrackingEventListener interface, and register the listener with the Veeplay Player.

public class FullscreenActivity extends FragmentActivity implements APSMediaPlayerTrackingEventListener {
...
@Override
public void onTrackingEventReceived(MediaEventType type,
ArrayList urls, String description) {
if(type == APSMediaEvents.MediaEventType.FULLSCREEN)
Toast.makeText(FullscreenActivity.this, "Fullscreen entered", Toast.LENGTH_SHORT).show();
else if(type == APSMediaEvents.MediaEventType.EXIT_FULLSCREEN)
Toast.makeText(FullscreenActivity.this, "Fullscreen exited", Toast.LENGTH_SHORT).show();
}
}

When initializing the player (or any time you wish to start receiving events):

APSMediaPlayer.getInstance().addTrackingEventListener(this);

When you no longer want to receive events:

APSMediaPlayer.getInstance().removeTrackingEventListener(this);

Event Names#

Event NameEvent
LaunchLAUNCH
StartSTART
FinishFINISH
Playlist FinishedPLAYLIST_FINISHED
Exit FullscreenEXIT_FULLSCREEN
Enter FullscreenFULLSCREEN
Toggle Fullscreen
ImpressionIMPRESSION
Viewable ImpressionVIEWABLE_IMPRESSION_VIEWABLE
Impression Not ViewableVIEWABLE_IMPRESSION_NOT_VIEWABLE
Impression With Undetermined ViewabilityVIEWABLE_IMPRESSION_UNDETERMINED
Creative ViewCREATIVE_VIEW
PausePAUSE, USER_PAUSE
ResumeRESUME, USER_UNPAUSE
RewindREWIND
ForwardFORWARD
MuteMUTE
UnmuteUNMUTE
ErrorERROR
CompleteCOMPLETE
CloseCLOSE
Video CloseCLOSE_LINEAR
SkipSKIP
ClickCLICK
Icon View
Ad Expand
Ad Collapse
PositionPOSITION
Seeked
SSAI Ad StartedSSAI_AD_STARTED
SSAI Ad EndedSSAI_AD_ENDED
Ad Break StartedADBREAK_TRIGGERED
Ad RequestedAD_REQUESTED
Ad Request CompleteAD_REQUEST_COMPLETE
Ad Request ErrorAD_REQUEST_ERROR
Ad Break EmptyADBREAK_EMPTY
Unit FinishedUNIT_FINISHED, UNIT_FINISHED_URL
Invalid LicenseLICENSE_INVALID
Playback Status ChangePLAYBACK_STATE_CHANGED
Load State ChangeBUFFER_START, BUFFER_END
Unit StartedSTART_PROCESSING_NEW_UNIT
Playback RequestedPLAYBACK_REQUESTED
Player Tapped
Controls Displayed
Controls Hidden
UpdateCLOCK_TICK
Event Tracked
Will Open Browser
Will Close Browser
Duration Available
Volume Changed
Mouse Move
Last updated on by Andrei Marinescu