Skip to content

SDK Reference

Introduction

The overlay SDK is a JavaScript library for integrating the Singular Graphics output into video players.

This section provides a reference to all Singular Overlay SDK function calls.

For more in-depth instructions on implementation, see our Overlay SDK Developer Guide. To see example code for each API call, visit out Overlay SDK Demos and search by call.


Getting Started

Include the Singular Overlay JavaScript library into your html code:

1
2
3
4
<head>
  <!-- Include the Singular Overlay JavaSrcipt library -->
  <script src="https://app.singular.live/libs/singularoverlay/0.1.0/singularoverlay.js"></script>
</head>

Add a div to your html code for the Singular Overlay instance:

1
2
3
4
<body>
  <!-- inside the div the iFrame of the overlay will be created -->
  <div id="SingularOverlay" style="width:720px; height: 400px;"></div>
</body>

Overlay SDK Functions

SingularOverlay(domElement, options, callback)

Create an instance of a Singular overlay with the following code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
var options = {
  class: "iFrameClass",
  endpoint: "http://app.singular.live",
  interactive: true,
  syncGraphics: false,
  showPreloader: false,
  aspect: "",
};

var overlay = SingularOverlay("#DomElement", options, (params) => {
  // callback code goes here
});
ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
domId The target div that the SingularOverlay will replace String Yes
options configuration options to define how to render the overlay. See the Configuration Option Description below. JSON Yes
callback Callback function called when the overlay object has been created Function Yes

Config Option Description

SETTING DESCRIPTION TYPE DEFAULT
class can be used to style the iFrame that the overlay SDK creates class iFrameClass
endpoint This is optional and can be used to work with different singular servers. String app.singular.live
delay Is specified in milliseconds and tells the overlay SDK to execute commands coming through Firebase later. String 0
interactive tells the overlay if it should handle mouse events. This will simply set pointer-events: none on the iFrame that is created. Boolean true
syncGraphics tells the render engine to synchronize graphics to UTC time received by videoSegment calls. Boolean false
showPreloader shows or hides the animation indicating that graphics is loading Boolean false
aspect defines the aspect ratio of the graphics window. When unspecified the graphics will cover 100% of the iFrame. String empty

Adaptive Config Option Description

Additionally you can use the Adaptive Parameters to define one specific adaptive layout define in the composition

SETTING DESCRIPTION TYPE DEFAULT
screenSize select class iFrameClass
layout String app.singular.live
textDirection String 0
interactive Boolean true
language Boolean false
custom1 Boolean false
custom2 String empty
custom3 String empty

setContent(content, callback)

Load a Singular graphic into the overlay instance.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
content Content can be a string or an object containing one of the values described below String or JSON Yes
callback Callback function called when the content has been loaded Function Yes

Options to define the content

SETTING DESCRIPTION TYPE DEFAULT
string Composition Revision URL String -
compToken Composition Token String -
appOutputToken App Output Token String -
webOutputToken Web Output Token String -

Sample

1
2
3
overlay.setContent(content, (params) => {
  // called when content finished loading
});

Content Options

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
// defining composition revision URL as string
var content = "https://assets.singular.live/f12f184c9a0eb763beb40478e02a1250/jsons/5E2QFRRjiRjN7n4AZUJPzq.json";
// defining composition token as string
var content = "6IX8LkY32V3KACSNvs0MnT";
// defining composition token in content object
var content = { compToken: "6IX8LkY32V3KACSNvs0MnT" };
// defining app output token in content object
var content = { appOutputToken: "6IX8LkY32V3KACSNvs0MnT" };
// defining web output token in content object
var content = { webOutputToken: "49bb0fyieZMUWAmQdbeajI" };

Locate the "Revision URL" in the Singular Composer

image user permissions

addListener(type, callback)

Add listener for events coming from the overlay.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
type Object containing one of the values described below String Yes
callback Callback function for the type of event Function Yes

Values for listener type

SETTING DESCRIPTION
message Listen to messages from the interactive layer code and send messages back to the video player.
error Listen to errors reported by the Overlay Instance

Sample: Listen to message from interactive layer code

1
overlay.addListener("message", (params) => {});

**Sample: Listen to error reported by the Overlay Instance **

1
overlay.addListener("error", (params) => {});

setDelay(delay)

Define the delay for the execution of incoming graphics control commands.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
delay Delay in milliseconds Number Yes

Sample

1
overlay.setDelay(500);

show()

Shows the graphics overlay by setting the iFrame visibility to visible.

hide()

Hides the graphics overlay by setting the iFrame visibility to hidden.

destroy()

Delete the graphics overlay.

videoPlaying()

Notifiy the overlay SDK that the video is playing.

videoPaused()

Notifiy the overlay SDK that the video is paused.

videoBuffering()

Notifiy the overlay SDK that the video is buffering.

videoStopped()

Notifiy the overlay SDK that the video is stopped.

videoFinished()

Notifiy the overlay SDK that the video is finished.

videoSeeking(time)

Notifiy the overlay SDK that the video is seeking at a specific time. Time is in seconds.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
time Time in seconds Number Yes

Sample

1
overlay.videoSeeking(500);

videoSeeked()

Notifiy the overlay SDK that the seeking operation is finished.

videoTime(time)

Send the current time of the video to the overlay SDK.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
time Time in seconds Number Yes

Sample

1
overlay.videoTime(60.0);

videoMetadata(object)

Sends information about the video. This info can be received in the interactive layer code.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
object description of object here object Yes

videoMuted()

The user clicked the mute button in the video player.

videoUnmuted(value)

The user clicked the mute button in the video player again.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
value The volume of the video Number Yes

videoVolume(value)

The user changed the volume of the video.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
value The volume of the video Number Yes

Sample

1
overlay.videoVolume(value);

videoAdStart(), videoAdFinished(), videoAdSkip()

The video player is playing an advertisement. The interactive layer can then hide certain graphics.

videoSegment(time)

UTC time we receive from the video which the overlay SDK can use to synchronize graphics to the video. The format of time is unix timestamp.

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
time Time in the format of the unix timestamp String Yes

Sample

1
overlay.videoSegment(500);

message(object)

Send a message to the interactive layer. Use this

ATTRIBUTE(s) DESCRIPTION TYPE REQUIRED
object description of object here object Yes

Sample

1
overlay.message(object);

Find more documentation

  • Singular Overlay SDK Developer Guide: here...
  • Singular Overlay SDK Demos and Code Examples: here....

Getting Help