Player API

This article explains the basics of how to use the JavaScript API component of Primis Player in a Web environment.

The player object allows registering custom callbacks to events, that are triggered inside the video player, such as when video content starts playing or when the user clicks on an ad.

Initializing The Player API

Embedding the player tag with an ID
In order to activate the Primis API feature, it is necessary to add a unique player ID into the player embed tag code. This identifier also lets you differentiate between players, in case you have more than one on the same page.

Example:

<script type="text/javascript" language="javascript" src="http://live.primis.tech/live/liveView.php?s=XXXXX&cbuster=[CACHE_BUSTER]&pubUrl=[PAGE_URL_ENCODED]&x=[WIDTH]&y=[HEIGHT]&playerApiId=[MY_PLAYER_ID]"></script>

📘

Player API ID

Please choose your Player ID. You may use both letters and numbers.
The player tag and the relevant section on the page should contain the exact Player ID value.

❗️

The Primis video player API is not supported when embedding the tag inside a safe frame or non-friendly iframe.

Get the Primis Player object when ready
When the video player finishes loading, a javascript event primisPlayerInit is triggered by the dispatchEvent method on the window.top object.

This event has the Player object attached to it, and can be uniquely identified by its playerApiId variable (as was defined in the embed tag).

This Player object can be referenced and stored in a local variable as shown below for later usage.

Example:

window.addEventListener('primisPlayerInit', function (e) {
 if (e.detail.playerApiId == '[MY_PLAYER_ID]')
 {
  var primisPlayer = e.detail;
 }
});

Events

After the Primis Player is loaded on the page, using the Player object, it is possible to register to events in order to get notifications when those events occur. It is also possible to unregister from events.

Register to Events

Without cbParams
Using the player object, add a callback function that will be executed when the desired event is triggered. Notice that these types of events are triggered without any extra information. Therefore, the callback function doesn`t need any parameters.

Example:

primisPlayer.addEventListener('videoStart', function (){ //do something;} );

With cbParams
Some events are triggered along with extra information that is sent with the event object. It is possible to reference the extra information through the callback function by adding a parameter to the function declaration.

Example:
The volumeChange event is triggered when the volume in the player is set to a new value. The new value is sent as a parameter to the registered callback function:

primisPlayer.addEventListener('volumeChange', function (newVal){ console.log(newVal); });

Unregister from Event
Unregister from event is possible by using the returned object from the addEventListener function as an argument to the remove function.

Example:

var resObj = primisPlayer.addEventListener('videoStart', function (){ //do something;} );
primisPlayer.removeEventListener(resObj);primisPlayer.addEventListener('videoStart', function (){ //do something;} );

Event Types
The following event types can be registered by using the player object:

Ⅰ. Ad Events

eventType

cbParams

Description

adStarted

Object
{impValue: float number,
servingFee: float number}

Ad impression - a new ad has begun playing.
If the pricing model is revShare, impValue has the impression value, otherwise the value is zero.
servingFee is Primis fee for serving the ad impression.
The values are in CPM (i.e. should be divided by 1000 in order to get this single impression value). In order to get the Net revenue for the impression, servingFee should be substructed from impValue.

Net Imp. Value in CPM = (impValue - servingFee)

Net Imp. Value = (impValue - servingFee)/1000

adCompleted

N/A

Ad completed playing fully

adFirstQuartile

N/A

Ad reached its first duration quartile

adMidQuartile

N/A

Ad reached second quartile

adThirdQuartile

N/A

Ad reached third quartile

adClickthrough

N/A

User clicked through the ad

adPause

N/A

Ad was manually paused by user

adPlay

N/A

Ad was manually resumed by user

adSkip

N/A

Ad was manually skipped by user

Ⅱ. Playlist Events

eventType

cbParams

Description

videoStart

Object
{title: string,duration: string}

A new content video was loaded and began playing (title is the video title and duration - video length)

videoEnd

N/A

Content Video completed playing fully

videoSkip

N/A

Content Video skipped by user

videoClickthrough

N/A

User clicked through the video

Ⅲ. Player Notifications Events

eventType

cbParams

Description

volumeChange

value: float between 0.0 - 1.0

Volume changed to value

playerModeChange

value: string

Value can be fullscreen/normal

floatStatusChange

value: integer

Allow the publisher to get the floating unit state changes. state will be changed to “0” in case there is no floating, and will be equal to “1” when the floating unit is viewable.

The Player Object Reference

This is the interface that is supported through the player object:

Functions

(object) callbackId addEventListener (eventType, callback)

Register a callback to an event:

  • eventType (string): The type of the event to register to
  • Callback (function): The callback function to invoke upon the occurrence of the eventType event
  • Return value: Object, specifying the unique identifier of the callback in the event-callback system. It allows the user to remove that specific callback if desired, or null if failed
(void) removeEventListener (object)

Remove a registered callback with the given callback id:

  • (object) object: The object that was returned from the addEventListener method upon registering the callback to the event type
  • Return value: N/A

Public Variables

  • (int) playerApiId: The unique id of the player as was set in the embed tag by the user and uniquely identifies this player object
  • (String array) allowedEvents: The names of the events that are supported by this player object

Full Code Example

A full test page example, which registers to videoStart and volumeChange events, and prints them to the test page when they arrive:

<!doctype html>
<html>
<head>
 <meta charset="utf-8">
 <title>PLAYER API</title>
</head>
<body>
<script type="text/javascript">
window.top.addEventListener('primisPlayerInit', function (e) {
 if (e.detail.playerApiId == '123')
 {
  var player = e.detail;
  player.addEventListener('videoStart', function (val){logEvent('videoStart', val.title);});
  player.addEventListener('videoEnd', function (){logEvent('videoEnd');});
  player.addEventListener('adStarted', function (val){logEvent('adStarted', val.impValue);});
  player.addEventListener('volumeChange', function(val){logEvent('volumeChange', val);});
 }
});

function logEvent(e, val)
{
 document.getElementById('event_prints').innerHTML += 'Event: '+e;
 document.getElementById('event_prints').innerHTML += val !== undefined?'['+val+']':'';
 document.getElementById('event_prints').innerHTML += '';
}
</script>
<!-- code from primis -->
<script type="text/javascript" language="javascript" src="http://live.primis.tech/live/liveView.php?s=XXXXX&cbuster=98765&pubUrl=example.com&x=300&y=250&vp_template=5579&playerApiId=123"></script>
<!-- code from primis -->
 <p id="event_prints"></p>
</body>
</html>

Player Actions

📘

If you want to use this feature please reach out to your publisher success manager to enable it

This section describes how to control Primis Player through Javascript API.
To enable player actions you must set a Player API ID as instructed in Initializing the player.

The following actions are supported:

Control Floating Behavior

  1. Optional: If you want to change the starting behavior of the player regarding floating behavior, please follow this guideline.
    Set a listener for 'readyConfigPlayerApi' to set the desired initial float status, example:
window.addEventListener('readyConfigPlayerApi', function (e){
        // get config object from the event
        var primisConfig = e.detail;
            // call setConfig function and pass an initialConfig object
        primisConfig.setConfig ({
            floatInitalStatus : "disable"
        })
    });
  1. Once you get the Primis Player object as described in initializing the player section, you can call the 'float' function with the relevant value 'enable'/'disbale', example:
window.addEventListener('primisPlayerInit', function (e) {
        if (e.detail.playerApiId == '123')
        {
            var primisPlayer = e.detail;

            setTimeout(function(){
                //activate float behavior 3 seconds after player starts
                primisPlayer.float('enable');
            },3000)
        }
    });

Initial config object

This table describes the structure of the required object for 'setConfig' function

Key

Value

floatInitalStatus - Required initial float status

(string) “enable“ / “disable"

Action functions

Function

Function Parameters

(void) float(action)

action:
"enable" - use the regular floating behavior which means go floating only when the docking unit is not in view.
"disable" - player will return immediately to the docking unit and no longer will go floating.


Did this page help you?