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.


<script type="text/javascript" language="javascript" src="[CACHE_BUSTER]&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 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.


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


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.


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.

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.


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

impValue: float
servingFee: float
playerWidth: integer
playerHeight: integer
domain: string
countryCode: string
Ad impression - a new ad has begun playing.
If revShare is used, ImpValue contains the impression value.
The values are in CPM (i.e. divided by 1000 to get this single impression value).
servingFee is Primis fee for serving the ad impression.
Net Imp. Value in CPM = ( impValue - servingFee)
Net Imp. Value = ( impValue - servingFee ) / 1000
adCompletedN/AAd completed playing fully
adFirstQuartileN/AAd reached its first duration quartile
adMidQuartileN/AAd reached second quartile
adThirdQuartileN/AAd reached third quartile
adClickthroughN/AUser clicked through the ad
adPauseN/AAd was manually paused by user
adPlayN/AAd was manually resumed by user
adSkipN/AAd was manually skipped by user

Ⅱ. Playlist Events

{title: string,duration: string}
A new content video was loaded and began playing (title is the video title and duration - video length)
videoEndN/AContent Video completed playing fully
videoSkipN/AContent Video skipped by user
videoClickthroughN/AUser clicked through the video

Ⅲ. Player Notifications Events

volumeChangevalue: float between 0.0 - 1.0Volume changed to value
playerModeChangevalue: stringValue can be fullscreen/normal
floatStatusChangevalue: integerAllow 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.
userFloatClose-This event will be triggered once the user clicks on the dismissal button of the floating unit

The Player Object Reference

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


(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,videoEnd,adStarted and volumeChange events, and prints them to the test page when they arrive:

<!doctype html>
 <meta charset="utf-8">
 <title>PLAYER API</title>
<script type="text/javascript">'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 += '';
<!-- code from primis -->
<script type="text/javascript" language="javascript" src=""></script>
<!-- code from primis -->
 <p id="event_prints"></p>

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;

				//activate float behavior 3 seconds after player starts

Initial config object

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

floatInitalStatus - Required initial float status(string) “enable“ / “disable"

Action functions

FunctionFunction 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.