Developer Documentation - OmniVirt Public API

 

   Download API sample code

 

Step 1) Upload your video into https://upload.omnivirt.com/

Step 2) Place default OmniVirt embed code. (screenshot)

Step 3) Place your custom API code inside <script> tag below default OmniVirt embed code

Receive Message API

Below are the list of JavaScript callbacks to receive status and update from OmniVirt player. Inside callback function, you will receive both data and iFrame object of OmniVirt player associated to the event.

Syntax:

OmniVirt.api.receiveMessage(

scope,                        /* JS object        - JavaScript handle. Host event variable */

eventName,                /* String         - Event name from table below */

callbackFunction        /* Function        - Callback function with parameters */
);

Sample code:

OmniVirt.api.receiveMessage(
                
window,
                
'paused',

                function(type, data, iFrame) {

                        // Register a callback function into window scope.

                        // The event triggers this callback function whenever user pause the video.

                }
        
);

Event name

Data

Description

load

{
   maxQuality: 1 - 4,

    cardboard: on / off,

    quality: 1 - 4

}

Triggered after the player is initiated.

Data = JSON hash that contain player status and quality of the video.

started

null

Triggered after the video start playing

ended

null

Triggered after the video finish

paused

null

Triggered after user pauses the video

expanded

null

Triggered after the player is expanded into fullscreen

collapsed

null

Triggered when user exit fullscreen

skipped

null

Triggered when skip API is called to end current video

duration

value: float

This tells how long the video is. The event is triggered after the video is initialized.

Data = duration of the video (float value)

buffered

value: 0.0 - 1.0

This tells how many percentage the video has been buffered.

Data = percentage of video buffer ready (0-1)

progress

value: 0.0 - 1.0

This tells how many percentage the video has been completed.

Data = percentage of video buffer ready (0-1)

seeked

value: 0.0 - 1.0

Triggered when user jump into different timeline of the video.

Data = percentage of video buffer ready (0-1)

latitude

value: -90 to 90

Triggered whenever there’s a vertical movement on 360° view.

Data = 180° vertical degree range from -90 to 90. Middle point is at 0

longitude

value: 0 to 360

Triggered whenever there’s a horizontal movement on 360° view.

Data = 360° vertical degree range from 0 to 360. Middle point is at 180

audio

value: 0 to 1

Triggered when user change audio volume

cardboard

value: on, off

Triggered when user switch Cardboard mode between on and off

quality

value: 1 - 4

Triggered when user change video quality

4 = 4K

3 = HD

2 = 720p

1 = 480p

Send Message API

You can use JavaScript API to update or set a player status. To call this function, you need to specify the event name, value, and the identify of OmniVirt iFrame you’d like to communicate with.

Note: Send Message API works with embed player only. To use API inside Custom JS editor (video & banner editing), please use Broadcast Message API instead (see next section).

Syntax:

OmniVirt.api.sendMessage(

eventName,                        /* String        - Event name from table below */

data,                                /* JS value        - Type depends on event. See below */

iFrame,                                /* JS object        - identity of OmniVirt iFrame  */

executeWheniFrameReady        /* (optional)  */

);

Sample code:

// this move player progress into 50%

OmniVirt.api.sendMessage(
                
'seek',
                
0.5,
                
document.getElementById(‘ado-24’)
        );

Event name

Data

Description

play

null

Start or resume the video

pause

null

Pause the video

cardboard

value : on / off

Turn on or off Cardboard mode

enable

value : “gyroscope” or “carousel”

Enable gyroscope detection or carousel gallery feature

disable

value : “gyroscope” or “carousel”

Disable gyroscope detection or carousel gallery feature

audio

value : 0 - 1

Adjust audio volume

quality

value : 1 - 4

Adjust playback quality

4 = 4K

3 = HD

2 = 720p

1 = 480p

switch

string: “ID:<video_id>”
Example: “ID:24”

Stop playing current video and switch to the specified video ID instead

expand

null

Expand the video player into full screen

collapse

null

Exit full screen

skip

null

End current video and start the next one

seek

value : 0.0 - 1.0

Jump into different timeline of the video

latitude

value: -90 to 90

Adjust vertical angle of the current 360° view

longitude

value: 0 to 360

Adjust horizontal angle of the current 360° view

cameraFov

float: 0 to 360

Set how wide the camera should be visible in the viewport (in degree angle)

cameraFocalLength

float: 0 to 100

Set how wide the camera should be visible in the viewport (in distance)

cameraZoom

float: 0.1 to 10

Set zoom level of the camera

cameraAspect

float

Ratio of width & height of the content source

cameraFilmGauge

float

cameraFilmOffset

float

Use this camera API console to try different output from camera API

Broadcast Message API

This API perform as same functionality as Send Message API. But, instead of sending message into a single OmniVirt’s player, it send to all OmniVirt’s player on the page. Additionally, broadcastMessage function can be used inside OmniVirt’s Advanced Edit as well.

Syntax:

OmniVirt.api.broadcastMessage( eventName, data, executeWheniFrameReady );

Sample code:

        // This pause all OmniVirt player on the page. This also works inside Advanced Edit.

OmniVirt.api.broadcastMessage('pause', null);

Unbind Event API

You can use JavaScript API to unbind JavaScript callback functions from the scope. You can also specify eventName and function identity to unbind specific function.

Syntax:

OmniVirt.api.unbind(

scope,                        /* JS object        - JavaScript handle that host the event */

eventName,                   /* String        - (optional) Event name */

receiveMessageFunction  /* Function        - (optional) Specific function to remove */

);

Sample code:

        var myCallbackFunction = function(type, data, iframe) {

console.log( 'Hey My Video is Paused', type, data, iframe );

};

OmniVirt.api.receiveMessage(
                
window,
                'paused',

myCallbackFunction
);

// to remove this callback function, you can do either one of these

OmniVirt.api.unbind(window);                        // remove all callback functions

OmniVirt.api.unbind(window, 'paused');                // remove all ‘pause’ callback functions.

OmniVirt.api.unbind(window, 'paused', myCallbackFunction); // remove myCallbackFunction

Still have questions? Contact us at contact@omnivirt.com