JavaScript API reference for Viously video player

API Events

The following events provide a comprehensive overview of the various states and interactions within the Viously video player API, allowing developers to create rich and interactive video experiences for users:

Events

Event NameDescription
playerSetupThis event is emitted when the video player has been successfully set up, initializing necessary components and configurations.
playerReadyIndicates that the video player is fully loaded, initialized, and ready for playback.
playerPlayFired when the video playback starts.
playerClosedIndicates that the video player has been closed.
adSlateStartSignals the start of an ad slate (a group of ads) before the main content starts.
adSlateCompleteFired when the ad slate (a group of ads) is completed and the main content is ready to start.
adBannerStartIndicates that a banner ad is displayed.
adBannerCompleteIndicates that the banner ad is stopped.
adVastRequestFired when the VAST is requested.
adVastRequestErrorFired when the request returns either empty or an error.
adVastStartFired when the VAST starts.
adVastSkipFired when the VAST is skipped by the user.
adVastClickFired when the VAST is clicked by the user.
adVastCompleteFired when the VAST is complete.
contentStartIndicates the start of the main content video playback after the ads have been played.
contentCompleteFired when the main content video playback is completed, indicating the end of the video.
contentMutedSignals that the main video's audio state has changed, indicating that it has been muted by the user.
contentUnmutedSignals that the main video's audio state has changed, indicating that it has been unmuted by the user.
contentVolumeIndicates that the volume has been changed by user action.
contentResumeFired when the main content video playback resumes after being paused by the user.
contentPauseIndicates that the main content video playback has been paused by the user.
contentEnterFullscreenFired when the video player enters fullscreen mode.
contentExitFullscreenFired when the video player exits fullscreen mode.
contentSeekIndicates that the user has seeked the content by user action.
contentSeekForwardIndicates that the user has seeked forward.
contentSeekBackwardIndicates that the user has seeked backward.
contentHeartbeatFired every 5 seconds during the content playback.
contentWaitingFired when the next frame of the media is not available, delaying the playback.
contentStalledFired when the user agent is trying to fetch media data, but data is unexpectedly not forthcoming.
contentWaitingHeartbeatPeriodically checks if the video is buffering.
contentStalledHeartbeatPeriodically checks if the video is rebuffering.
contentErrorFired when content had an error.
contentQualityChangedFired when content quality is changed in the player, either by the user or automatically based on user bandwidth.

Using the API Events

Before subscribing to events in the Viously video player API, ensure that the vsly function is available in the window scope. You can do this by checking if vsly is defined. Here's an example of how to properly use the API, including handling cases where it might not be available yet:

1. Checking API Availability

Before using the API, make sure it's available in the window scope. You can check for its existence like this:

if (typeof vsly === "function") {
    // The vsly function is available, you can subscribe to events here
} else {
    // The vsly function is not available yet, wait for it to load or handle the situation accordingly
    console.log("The Video Player API is not available yet. Please wait for it to load.");
}

2. Subscribing to Events

Once you've confirmed the availability of the API, you can subscribe to events as described in the previous section.

a. Using a Closure:

vsly().once("playerPlay", function(e){
     // Your closure function logic here
});

b. Using a Named Function:

var myFunction = function(e) {
     // Your function logic here
     vsly().off("playerPlay", myFunction);
};

vsly().on("playerPlay", myFunction);

3. Specifying a VID (Optional)

If there are multiple players on the webpage, you can specify a VID (Video ID) as a parameter:

vsly(_MY_VID_).once("playerPlay", function(e){
     // Your closure function logic here
});

Note: If you don’t specify a VID, the API uses the first VID it finds on the webpage.

4. Handling Delayed API Load

If the vsly function is not immediately available, you can use the following approach to wait for it to load:

(function checkVsly() {  
    if (typeof vsly !== 'undefined') {  
        // The API is loaded, subscribe to the event  
        var myFunction = function(e) {  
            // Your function logic here  
            vsly().off("contentStart", myFunction);  
        };  
        vsly().on("contentStart", myFunction);  
    } else {  
        // Check again after a short delay  
        setTimeout(checkVsly, 100);  
    }  
})();

This ensures that your code will only run when vsly is available, avoiding potential errors.

Event Data

For all events triggered by the Viously video player, the callback function receives a data object containing detailed information about the current video content. This consistent data structure across different events enhances ease of use and predictability for API consumers.

Properties

The event data object provided to the callback function includes the following properties:

Property NameDescriptionAvailable on Events
event_nameThe name of the event that occurred. This string identifies which event was triggered in the video player.All events
event_timestampThe event time since the beginning of the browsing session.All events
session_idA unique identifier for the user's session. This string helps in tracking the user's interaction across different events and sessions.All events
template_idAn identifier for the template configuration of the player in the backoffice. This string specifies which template is being used for the video player configuration.All events
template_versionThe version of the template configuration being used. This string helps in identifying which version of the player template is active.All events
playlist_idThe unique identifier for the video playlist. This string specifies the playlist ID.All events
playlist_indexThe current index of the video being played in the playlist. This integer starts from 0.All events
playlist_typeThe type of the playlist. This string can be equal to top, last, random, or related.All events
content_vidA unique identifier for the video. It's a string that represents the video ID in the Viously system.All events
content_titleThe title of the video. This is a string that provides the name or description of the video content.All events
content_descriptionThe description of the video content. This string provides a detailed description of the video.All events
content_urlThe URL of the video. This string provides a direct link to the video's location on the Viously platform.All events
content_categoryThe category of the video content. This string indicates the category to which the video belongs.All events
content_durationThe duration of the video content in milliseconds. This integer provides the total duration of the video.All events
content_upload_dateThe upload date and time of the video. This string is in the format "YYYY-MM-DD HH:MM:SS", representing the date and time when the video was uploaded to the platform.All events
content_qualityThe current quality of the video with possible values:
240p SD
360p SD
480p SD
720p HD
1080p HD
All content events
content_error_messageThe video error message.contentError
content_external_sourceThe source of the video. It can be either an URL or an ID.All events
volumeThe volume represents the current audio volume level of the video. This float ranges from 0 to 1, with 0 indicating mute and 1 representing the maximum volume. This property allows for precise control and monitoring of the audio level in the video content.contentMuted
contentUnmuted
contentVolume
ad_typePossible values are :
preroll
banner
adVastRequest adVastRequestError
adVastStart
adVastSkip
adVastClick
adVastComplete
adBannerStart
adBannerComplete
ad_vast_typePossible values are:
booster
adserving
viously
adVastRequest adVastRequestError
adVastStart
adVastSkip
adVastClick
adVastComplete
ad_enginePossible values are:
google
prebid
adVastRequest adVastRequestError
adVastStart
adVastSkip
adVastClick
adVastComplete
adBannerStart
adBannerComplete
ad_vast_durationThe vast duration in seconds.adVastComplete
ad_error_codeThe VAST error code.adVastRequestError
ad_error_messageThe VAST error message.adVastRequestError
play_event_typeThe type of event that launched the player. This string describes the user action or condition that initiated video playback. Possible values are :
autoplay_muted
autoplay_audible
clicktoplay
scrolltoplay
playerPlay
player_position_onloadThe position of the player on the page when it loads. This string can be equal to above or below.All events
iab_playback_methodA code representing the playback method according to IAB standards. Possible values are :
1 : auto_play_sound_on
2 : auto_play_sound_off
3 : click_to_play
4 : mouse_over
5 : enter_sound_on
6 : enter_sound_off
playerPlay
user_is_botA boolean indicating if the user is a bot.All events
user_is_datacenter_ipA boolean indicating if the user's IP is from a datacenter.All events
user_is_adblockedA boolean indicating if the user has an ad blocker enabled.All events
user_is_anonymousA boolean indicating if the user is anonymous.All events
user_is_invalid_trafficA boolean indicating if the user traffic is considered invalid.All events
cursor_positionThe cursor position of the video in milliseconds.contentResume
contentPause
contentEnterFullscreen
contentExitFullscreen
contentMuted
contentUnmuted
contentVolume
contentSeek
contentHeartbeat
old_cursor_positionThe cursor position of the video in milliseconds before clicking.contentSeekForward
contentSeekBackward
new_cursor_positionThe cursor position of the video in milliseconds after clicking.contentSeekForward
contentSeekBackward

Using the data events

Structure of Event Data Object

{
    "event_name": "adVastComplete",
    "event_timestamp": 151564.8,
    "session_id": "e302f8560fb35d1604d3317ef5a2c0da",
    "content_vid": "g8dcUpw5zER",
    "content_title": "Crêpes faciles",
    "content_description": "Crêpes faciles",
    "content_category": "food",
    "content_url": "https://www.viously.com/cuisineaz/g8dcUpw5zER",
    "content_duration": 59,
    "content_upload_date": "2024-05-23 08:24:29",
    "content_author": null,
    "template_id": "PV727W65vPmdJ",
    "template_version": 33,
    "playlist_id": "",
    "playlist_index": 1,
    "playlist_type": "",
    "player_position_onload": "above",
    "user_is_bot": false,
    "user_is_datacenter_ip": false,
    "user_is_adblocked": false,
    "user_is_anonymous": false,
    "user_is_invalid_traffic": false,
    "ad_vast_type": "viously",
    "ad_vast_duration": 10,
    "ad_type": "preroll",
    "ad_engine": "google"
}

Access the data

To access this data, subscribe to an event using the vsly().on method. The callback function you provide will automatically receive the event data object as its argument:

vsly().on("playerPlay", function(eventData) {
  console.log("Event Name:", eventData.event_name);
  console.log("Session ID:", eventData.session_id);
  console.log("Template ID:", eventData.template_id);
  console.log("Template Version:", eventData.template_version);
  console.log("Video ID:", eventData.vid);
  console.log("Video Title:", eventData.title);
  console.log("Video URL:", eventData.url);
  console.log("Upload Date:", eventData.content_upload_date);
  console.log("Play Event Type:", eventData.play_event_type);
  console.log("IAB Playback Method:", eventData.iab_playback_method);
  console.log("Content Description:", eventData.content_description);
  console.log("Content Category:", eventData.content_category);
  console.log("Content Duration:", eventData.content_duration);
  console.log("Playlist ID:", eventData.playlist_id);
  console.log("Playlist Index:", eventData.playlist_index);
  console.log("Playlist Type:", eventData.playlist_type);
  console.log("Player Position Onload:", eventData.player_position_onload);
  console.log("User is Bot:", eventData.user_is_bot);
  console.log("User is Datacenter IP:", eventData.user_is_datacenter_ip);
  console.log("User is Adblocked:", eventData.user_is_adblocked);
  console.log("User is Anonymous:", eventData.user_is_anonymous);
  console.log("User is Invalid Traffic:", eventData.user_is_invalid_traffic);
  console.log("Content Quality:", eventData.content_quality);
  console.log("Ad Type:", eventData.ad_type);
  console.log("Ad VAST Type:", eventData.ad_vast_type);
  console.log("Ad Engine:", eventData.ad_engine);
  console.log("Ad VAST Duration:", eventData.ad_vast_duration);
  console.log("Ad Error Code:", eventData.ad_error_code);
  console.log("Ad Error Message:", eventData.ad_error_message);
  console.log("Content Error Message:", eventData.content_error_message);
});

This consistent data structure across events makes it easier for developers to interact with different aspects of the video player and handle various types of events in a uniform manner.