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 Name | Description |
---|---|
playerSetup | This event is emitted when the video player has been successfully set up, initializing necessary components and configurations. |
playerReady | Indicates that the video player is fully loaded, initialized, and ready for playback. |
playerPlay | Fired when the video playback starts. |
playerClosed | Indicates that the video player has been closed. |
adSlateStart | Signals the start of an ad slate (a group of ads) before the main content starts. |
adSlateComplete | Fired when the ad slate (a group of ads) is completed and the main content is ready to start. |
adBannerStart | Indicates that a banner ad is displayed. |
adBannerComplete | Indicates that the banner ad is stopped. |
adVastRequest | Fired when the VAST is requested. |
adVastRequestError | Fired when the request returns either empty or an error. |
adVastStart | Fired when the VAST starts. |
adVastSkip | Fired when the VAST is skipped by the user. |
adVastClick | Fired when the VAST is clicked by the user. |
adVastComplete | Fired when the VAST is complete. |
contentStart | Indicates the start of the main content video playback after the ads have been played. |
contentComplete | Fired when the main content video playback is completed, indicating the end of the video. |
contentMuted | Signals that the main video's audio state has changed, indicating that it has been muted by the user. |
contentUnmuted | Signals that the main video's audio state has changed, indicating that it has been unmuted by the user. |
contentVolume | Indicates that the volume has been changed by user action. |
contentResume | Fired when the main content video playback resumes after being paused by the user. |
contentPause | Indicates that the main content video playback has been paused by the user. |
contentEnterFullscreen | Fired when the video player enters fullscreen mode. |
contentExitFullscreen | Fired when the video player exits fullscreen mode. |
contentSeek | Indicates that the user has seeked the content by user action. |
contentSeekForward | Indicates that the user has seeked forward. |
contentSeekBackward | Indicates that the user has seeked backward. |
contentHeartbeat | Fired every 5 seconds during the content playback. |
contentWaiting | Fired when the next frame of the media is not available, delaying the playback. |
contentStalled | Fired when the user agent is trying to fetch media data, but data is unexpectedly not forthcoming. |
contentWaitingHeartbeat | Periodically checks if the video is buffering. |
contentStalledHeartbeat | Periodically checks if the video is rebuffering. |
contentError | Fired when content had an error. |
contentQualityChanged | Fired 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 Name | Description | Available on Events |
---|---|---|
event_name | The name of the event that occurred. This string identifies which event was triggered in the video player. | All events |
event_timestamp | The event time since the beginning of the browsing session. | All events |
session_id | A unique identifier for the user's session. This string helps in tracking the user's interaction across different events and sessions. | All events |
template_id | An 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_version | The version of the template configuration being used. This string helps in identifying which version of the player template is active. | All events |
playlist_id | The unique identifier for the video playlist. This string specifies the playlist ID. | All events |
playlist_index | The current index of the video being played in the playlist. This integer starts from 0. | All events |
playlist_type | The type of the playlist. This string can be equal to top , last , random , or related . | All events |
content_vid | A unique identifier for the video. It's a string that represents the video ID in the Viously system. | All events |
content_title | The title of the video. This is a string that provides the name or description of the video content. | All events |
content_description | The description of the video content. This string provides a detailed description of the video. | All events |
content_url | The URL of the video. This string provides a direct link to the video's location on the Viously platform. | All events |
content_category | The category of the video content. This string indicates the category to which the video belongs. | All events |
content_duration | The duration of the video content in milliseconds. This integer provides the total duration of the video. | All events |
content_upload_date | The 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_quality | The current quality of the video with possible values:240p SD 360p SD 480p SD 720p HD 1080p HD | All content events |
content_error_message | The video error message. | contentError |
content_external_id | The source ID of the video. | All events |
content_external_source | The source URL of the video. | All events |
volume | The 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_type | Possible values are :preroll banner | adVastRequest adVastRequestError adVastStart adVastSkip adVastClick adVastComplete adBannerStart adBannerComplete |
ad_vast_type | Possible values are:booster adserving viously | adVastRequest adVastRequestError adVastStart adVastSkip adVastClick adVastComplete |
ad_engine | Possible values are:google prebid | adVastRequest adVastRequestError adVastStart adVastSkip adVastClick adVastComplete adBannerStart adBannerComplete |
ad_vast_duration | The vast duration in seconds. | adVastComplete |
ad_error_code | The VAST error code. | adVastRequestError |
ad_error_message | The VAST error message. | adVastRequestError |
play_event_type | The 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_onload | The position of the player on the page when it loads. This string can be equal to above or below . | All events |
iab_playback_method | A 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_bot | A boolean indicating if the user is a bot. | All events |
user_is_datacenter_ip | A boolean indicating if the user's IP is from a datacenter. | All events |
user_is_adblocked | A boolean indicating if the user has an ad blocker enabled. | All events |
user_is_anonymous | A boolean indicating if the user is anonymous. | All events |
user_is_invalid_traffic | A boolean indicating if the user traffic is considered invalid. | All events |
cursor_position | The cursor position of the video in milliseconds. | contentResume contentPause contentEnterFullscreen contentExitFullscreen contentMuted contentUnmuted contentVolume contentSeek contentHeartbeat |
old_cursor_position | The cursor position of the video in milliseconds before clicking. | contentSeekForward contentSeekBackward |
new_cursor_position | The 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.
For any queries or assistance, please reach out to [email protected].
Updated about 1 month ago