JavaScript

Introduction
What is the Spotlightr JavaScript API?

Spotlightr API opens up below defined set of methods and events you can use to:

  • Send commands and data to the video player from your web page.
  • Listen to events in the player from the web page and react.

Here are just a few real-world examples that showcase what the Spotlightr API enables you to do. Keep in mind that the combinations are infinate and only limited by your imagination.

  • Show content on your page only when a certain timepoint in the video is reached.
  • Prefill and autocomplete optin boxes in the video with data from your website or URL.
  • Pause or play the video based on certain interactions on the web page
Simple example

A simple call may look like:

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'play')"> Play Video </button>

Here we specify a on click action which uses the spotlightrAPI function. This is the global access function for all the methods and events.

In the function we are passing two paramaters, the video id (MTM1MjA5MA==) of the video to reach, and the method ('play') you want to initiate.

So the expected result is that once the button is clicked the video with the id MTM1MjA5MA== will play.

Use of the JavaScript API requires the presence of spotlightr.js script in your embed code, meaninig that when publishing videos, advanced embed code needs to be turned on.


spotlightrAPI Methods

Methods work by passing video id, desired method you want to initiate and an optional paramater.


play

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'play')"> Play Video </button>
Description

Triggers the video player play event and play the video.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes

Example

See the Pen CodePen HTML by devuser (@spotlightr-demo) on CodePen.


pause

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'pause')"> Pause Video </button>
Description

Triggers the video player pause event and pause the video.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes

captions

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'captions', true)"> captions </button>
Description

Hide or show captions


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Boolean Show or hide captions Yes

volume

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'volume', [.5])"> Set volume to 50% </button>
Description

sets the volume to the video.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Increasing or decreasing value of volume Yes

source

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'source', ['MTM1MjA5MA==','5'])"> Set Source </button>
Description

Triggers the video player source event, and sets the current time.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Set VideoId and Source Time Yes

Example

See the Pen CodePen HTML by devuser (@devuser007) on CodePen.


showControls

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'showControls', [1])"> Toggle Controls visibility </button>
Description

show the control of the video player.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Set control visibility Yes

hideControls

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'hideControls', [0])"> Toggle Controls visibility </button>
Description

hide the control of the video player.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Set control visibility Yes

imageOnPause

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'imageOnPause', [0])"> </button>
Description

Disable already enabled image on pause.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Set show image on pause Yes

currentTime

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'currentTime', [30])"> Set Time To 30 </button>
Description

sets current time of the player to given value in seconds.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Set current time of video Yes

getTime

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'getTime', ['3','6'], getTime)">
  Set Listener
</button>
<script>
  function getTime(time){
  console.log('[vp]getTime',time);
  //DO STUFF HERE
  }
</script>
Description

Triggers the callback at specified seconds from the begning of the video.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Time of video Yes
callback function function Callback function for get time Yes

getCurrentTime

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'getCurrentTime', null, getCurrentTime)">
  Set Listener
</button>
<script>
  function getCurrentTime(time){
  console.log('[vp]getCurrentTime',time);
  //DO STUFF HERE
  }
</script>
Description

Get Current Time of a video.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array - No
callback function function Callback function to get current time Yes

getDuration

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'getDuration', null, getDuration)">
  Set Listener
</button>
<script>
  function getDuration(duration){
  console.log('[vp]getDuration',duration);
  //DO STUFF HERE
  }
</script>
Description

Gives duration of the loaded video.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Duration of video Yes
callback function function Callback function for get duration Yes

Example

See the Pen CodePen HTML by devuser (@devuser007) on CodePen.


setRemainingTime

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'setRemainingTime', ['25','20'], setRemainingTime)">
  Set Listener
</button>
<script>
  function setRemainingTime(time){
  console.log('[vp]setRemainingTime',time);
  //DO STUFF HERE
  }
</script>
Description

Triggers callback at specified times in seconds before the end of the video.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Set remaining time of video Yes
callback function function Callback function for set remaining time Yes

addNewPlayerSettings

<button type="button" name="button" onclick="addNewPlayerSettings()">
  Add New Player Settings
</button>
<script>
  function addNewPlayerSettings(time){
    const playerId = 'MTM1MjA5MA=='
    function addNewPlayerSettings() {
        const newPlayerSettings = {
            alwaysVisibleControls: true,
            colors: {
                bars:"#fa07d8ff",
                controls:"#5aff2aff",
                skin:"#fff",
            }
        }   
        spotlightrAPI(playerId, 'addNewPlayerSettings', newPlayerSettings)     
    }
  }
</script>
Description

Add new player settings to a video.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for adding new player settings to a video Yes
Method Parameter Object New player settings Yes

Example

See the Pen Untitled by devuser (@devuser007) on CodePen.


completeOptin

<script>
function completeOptin(){
  spotlightrAPI('MTM1MjA5MA==', 'completeOptin', ["test@test.com"]);
}
</script>
Description

Set pre-defined email for email optin lock (must be triggered before the optin is shown).


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Value of complete optin Yes

setCustomViewerID

<script>
function setCustomViewerID(){
  spotlightrAPI('MTM1MjA5MA==', 'setCustomViewerID', ["member_123"]);
}
</script>
Description

Sets customViewerId for the video.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Customer viewer id Yes

sendVideoAnalytics

<script>
function sendVideoAnalytics(){
  spotlightrAPI('MTM1MjA5MA==', 'sendVideoAnalytics');
}
</script>
Description

Triggers the video player sendVideoAnalytics event and sned the video analytics data. Like device, percentWatched, watchedSegments, bandwidth, reportedBandwidth etc...


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes

showLocks

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'showLocks', [1 OR 0])"> Show Locks </button>
Description

Sets visibility of lock, 0 don't show lock 1 show lock.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Set value for show lock in 0 or 1 Yes

showOverlays

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'showOverlays', [1 OR 0])"> Show Overlays </button>
Description

Sets visibility of overlays, 0 don't show overlay 1 show overlay.


Parameters
Field Type Description Required
Video Id number Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter Array Set value for show overlays in 0 or 1 Yes


spotlightrAPI Events

Events are called the same way as methods, with the addition of providing a callback function when the desired event is fired.

vooPlayerReady

<script>
document.addEventListener('vooPlayerReady', vooPlayerReady, false);

function vooPlayerReady(event){
    console.log("[vp]vooPlayerReady",event);
    spotlightrAPI("MTM1MjA5MA==", 'getDuration', null, getDurationCallback);
    spotlightrAPI("MTM1MjA5MA==", 'setRemainingTime', ['25','20'], setRemainingTime);
    spotlightrAPI("MTM1MjA5MA==", 'getTime', ['3','6'], getTime);
    spotlightrAPI("MTM1MjA5MA==", 'onPause', null, onPause);
  }
  function getDurationCallback(duration){
    console.log("[vp]getDurationCallback",duration);
  }
  function setRemainingTime(time){
    console.log("[vp]setRemainingTime",time);
  }
  function getTime(time){
    console.log("[vp]getTime",time);
  }
  function onPause(){
    console.log("[vp]onPause");
  }
</script>
Description

We made our event called 'vooPlayerReady'. If you want to know and to be sure that your video is loaded and ready for manipulating you can add listener for it.


Example

See the Pen CodePen HTML by devuser (@devuser007) on CodePen.


onEnded

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'onEnded', null, onVideoEnded)">
  Set Listener
</button>
<script>
  function onVideoEnded(){
    console.log('[vp]onVideoEnded');
    //DO STUFF HERE
  }
</script>
Description

Trigger this event when video is ended.


Parameters
Field Type Description Required
Video Id string Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter null null No
Callback function function Callback function for onEnded Yes

Example

See the Pen CodePen HTML by devuser (@devuser007) on CodePen.


onPlay

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'onPlay', null, onVideoPlay)">
  Set Listener
</button>
<script>
  function onVideoPlay(){
    console.log('[vp]onVideoPlay');
    //DO STUFF HERE
  }
</script>
Description

Trigger this event when video is played.


Parameters
Field Type Description Required
Video Id string Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter null null No
Callback function function Callback function for onVideoPlay Yes

onPause

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'onPause', null, onVideoPaused)">
  Set Listener
</button>
<script>
  function onVideoPaused(){
    console.log('[vp]onVideoPaused');
    //DO STUFF HERE
  }
</script>
Description

Trigger this event when video is paused.


Parameters
Field Type Description Required
Video Id string Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter null null No
Callback function function Callback function for onVideoPaused Yes

onSeeked

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'onSeeked', null, onVideoSeeked)">
  Set Listener
</button>
<script>
  function onVideoSeeked(time){
  console.log('[vp]onVideoSeeked', time);
  //DO STUFF HERE
}
</script>
Description

Handling the event when video is seeked.


Parameters
Field Type Description Required
Video Id string Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter null null No
Callback function function Callback function for onVideoSeeked Yes

onAnswerSubmitted

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'answerSubmitted', null, onAnswerSubmitted)">
  Set Listener
</button>
<script>
  function onAnswerSubmitted(answerData){
  console.log('[vp]onAnswerSubmitted', answerData);
  //DO STUFF HERE
}
</script>
Description

Handling the event when quiz answer is submited.


Parameters
Field Type Description Required
Video Id string Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter null null No
Callback function function Callback function for onVideoSeeked Yes

onQuizFinished

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'quizFinished', null, onQuizFinished)">
  Set Listener
</button>
<script>
  function onQuizFinished(results){
  console.log('[vp]onQuizFinished', results);
  //DO STUFF HERE
}
</script>
Description

Handling the event when quiz is finished.


Parameters
Field Type Description Required
Video Id string Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter null null No
Callback function function Callback function for onVideoSeeked Yes

onResolutionChange

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'onResolutionChange', null, onResolutionChange)">
  Set Listener
</button>
<script>
  function onResolutionChange(data){
  console.log('[vp]onResolutionChange', data.returnValue);
  //DO STUFF HERE
}
</script>
Description

Handling the event when resolution change.


Parameters
Field Type Description Required
Video Id string Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter null null No
Callback function function Callback function for onResolutionChange Yes

onPlaybackSpeedChange

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'onPlaybackSpeedChange', null, onPlaybackSpeedChange)">
  Set Listener
</button>
<script>
  function onPlaybackSpeedChange(data){
  console.log('[vp]onPlaybackSpeedChange', data.returnValue);
  //DO STUFF HERE
}
</script>
Description

Handling the event when playback speed change.


Parameters
Field Type Description Required
Video Id string Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter null null No
Callback function function Callback function for onPlaybackSpeedChange Yes

onVolumeChange

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'onVolumeChange', null, onVolumeChange)">
  Set Listener
</button>
<script>
  function onVolumeChange(data){
  console.log('[vp]onVolumeChange', data.returnValue);
  //DO STUFF HERE
}
</script>
Description

Handling the event when volume change.


Parameters
Field Type Description Required
Video Id string Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter null null No
Callback function function Callback function for onVolumeChange Yes

onFullscreenChange

<button type="button" name="button" onclick="spotlightrAPI('MTM1MjA5MA==', 'onFullscreenChange', null, onFullscreenChange)">
  Set Listener
</button>
<script>
  function onFullscreenChange(data){
  console.log('[vp]onFullscreenChange', data.returnValue);
  //DO STUFF HERE
}
</script>
Description

Handling the event when fullscreen change.


Parameters
Field Type Description Required
Video Id string Id of a Video Yes
Api Method string Method for spotlightrAPI to trigger Yes
Method Parameter null null No
Callback function function Callback function for onFullscreenChange Yes


REST API

Introduction
What is the Spotlightr REST API?

Spotlightr REST API allows you to communicate with the Spotlightr database and servers using the here defined set of requests.

  • Upload a new video and apply predefined settings
  • Create a new video with predefined settings via link (youtube, vimeo, dropbox, etc/)

Use Cases & Example

Here are just a few real-world examples that showcase what the Spotlightr API enables you to do.

  • Generate a Spotlightr with predefined look and interactions by uploading a new file
  • Automatically brand YouTube videos and set locks on them
Authorization and Simple example

For accessing the REST API client must have an API Key. It can be generated through the application: Settings > Integrations & APIs > Spotlightr API Key > Get API key

Q: How to create new video with youtube link?
A: There is 3 required fields: vooKey, URL and name
  • vooKey: for API authentication
  • name: Name of the video
  • URL: stands for any link (youtube, gdrive, vimeo...)
Q: How to upload video through the API?
A: Same thing as for creating linked video, but you send file parameter, instead of URL.
  • vooKey: for API authentication
  • name: Name of the video
  • file: Attach the video file for upload
Q: What if I send both URL and file parameter?
A: In that case, we are creating linked video with URL (URL has priority in that case)

Q: Can user use playerSettings of any video from Spotlightr?
A: He can use only his videos playerSettings. He can't use somebody's videos ID. Parameter playerSettings is optional, and it needs to be video ID from which we want to copy playerSettings. If that parameter is empty, we will use default settings.

Making an API Request

createVideo

Endpoint

Method : POST
URL : https://api.spotlightr.com/api/createVideo

Description

It let's you to create a video in an application.

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
URL string Video URL Yes (unless file provided)
name string Video name Yes
customS3 number 0 or ID of custom integration Yes
hls number 1 - to encode OR 0 - to leave as unsecured No
videoGroup number Project ID No
create number 1 - to confirm OR 0 - to debug No
playerSettings object Video ID for coping playerSettings (decoded base64) No
file File File for upload Yes (unless URL provided)
Response
Created Video URL
https://brookerfieldrenewable.cdn.spotlightr.com/watch/MTM1NzgzNQ==
Example

See the Pen CodePen HTML by devuser (@devuser007) on CodePen.



Get Groups (Projects)

Endpoint

Method : GET
URL : https://api.spotlightr.com/groups

Description

Get projects

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes

Create Group (Projects)

Endpoint

Method : POST
URL : https://api.spotlightr.com/groups

Description

Create a new projects

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
name string Name of the Project Yes

videoSource

Endpoint

Method : GET
URL : https://api.spotlightr.com/api/videoSource

Description

Set new video source.

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
id number Video source to be replaced Yes
URL string New URL for the source Yes

deleteVideo

Endpoint

Method : POST
URL : https://api.spotlightr.com/api/deleteVideo

Description

Delete video from project.

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
IDs Array Array of ids to be deleted e.g. [1234,5678] Yes

getTopVideos

Endpoint

Method : GET
URL : https://api.spotlightr.com/api/getTopVideos

Description

Get top videos from the list.

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
days number Reporting Days (default is 30)
total number Number of top videos (default is 3)

metrics

Endpoint

Method : GET
URL : https://api.spotlightr.com/api/video/metrics

Description

Get video Analytics data.

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
videoID number Video Id Yes
Response
  {
    "loads": 301,
    "watched": 26.55,
    "plays": 8,
    "playRate": 2,
    "completitionRate": 0,
    "shares": 0
  }                     

getViews

Endpoint

Method : GET
URL : https://api.spotlightr.com/api/views/getViews

Description

Get video views.

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
videoID number videoMetrics Yes
customViewerID string id or email of a known viewer No
onlyWatched bool views with percentWatched > 1 (true|false)
allViews bool No data pagination (true|false)

videos

Endpoint

Method : GET
URL : https://api.spotlightr.com/api/videos

Description

Get videos.

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
videoID integer ID of a video No
videoGroup integer ID of a project No

domain (GET)

Endpoint

Method : GET
URL : https://api.spotlightr.com/api/user/domain

Description

Lists whitelisted domains

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes

domain (ADD)

Endpoint

Method : POST
URL : https://api.spotlightr.com/api/user/domain

Description

Adds whitelisted domain

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
domain string desired domain (e.g. example.com) Yes

codes

Endpoint

Method : POST
URL : https://api.spotlightr.com/spotlight/codes

Description

Create Gallery codes

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
quantity number Yes
id number Gallery ID Yes
never number 0 OR 1 never expires Yes
unlocks number 0 OR any number Yes
time number 0 OR any number Yes
expires date 0000-00-00 OR any YYYY-MM-DD Yes

updateCode

Endpoint

Method : POST
URL : https://api.spotlightr.com/spotlight/updateCode

Description

Update gallery access codes (expire them)

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
id number Code ID Yes
expires number 1 Yes
Endpoint

Method : POST
URL : https://api.spotlightr.com/search/global

Description

Search everything in your account

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes

Update Video Player Settings

Endpoint

Method : POST
URL : https://api.spotlightr.com/video/updateSettings

Description

Update individual player settings

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
id integer Video ID (base64 decoded value) Yes
settings json object Object containing only keys to be updated Yes

Upload an asset

Endpoint

Method : POST
URL : https://api.spotlightr.com/assets

Description

Upload an asset

Parameters
Field Type Description Required
vooKey string API Key (user's integrations api key) Yes
file file (form-data) File to be uploaded Yes


Query Params

Introduction
What are the Spotlightr Query Params?

Allows you to customize the URL of the Watch Page or source of the embedded iframe with added functionality.

For example: https://spotlightrteam.cdn.spotlightr.com/watch/MTMxNjk4NA==?t=62 will stat the video at 01:02

Parameters
Field Type Description
s number (seconds) Sets a starting point for your video.
e number (seconds) Set an ending point for your video.
omitView boolean Disables video analytics.
contact string (email / id) Identify a known viewer. Learn more
personalized boolean Personalize the viewers experience - if known viewer. Find more
resolution number (360,720,1080...) Set default resolution on the video.
aspect number Set the video aspect ratio.
videoBG string (hex color) Change video background color.
chapter number Set video to start by specified chapter index. Learn more
t number Sets video to a specific time