Links

SDK functions

SingularOverlay(domElement, options, callback)

Create an instance of a Singular overlay with the following code:
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
});
Attributes
Type
Required
Description
domId
String
Yes
The target div that the SingularOverlay will replace.
options
JSON
Yes
Configuration options to define how to render an overlay. See the config option description below.
callback
Function
Yes
Callback function called when the overlay object has been created.

Config option description

Setting
Type
Default
Description
class
class
iFrameClass
Can be used to style the iframe that the overlay SDK creates.
endpoint
String
app.singular.live
Optional. Can be used to work with different Singular servers.
delay
String
0
Specified in milliseconds. It tells the overlay SDK to execute commands coming through Firebase later.
interactive
Boolean
true
Tells the overlay if it should handle mouse events. This will simply set pointer-events: none on the iframe that is created.
syncGraphics
Boolean
false
Tells the render engine to synchronize graphics to UTC time received by videoSegment calls.
showPreloader
Boolean
false
Shows or hides the animation indicating that graphics are loading.
aspect
String
empty
Defines the aspect ratio of the graphics window. When unspecified, the graphics will cover 100% of the iframe.

Adaptive config option description

You can also use adaptive parameters to define a specific adaptive layout define in the composition.
Setting
Type
Default
Description
screenSize
Class
iFrameClass
Select
layout
String
app.singular.live
textDirection
String
0
0 ... left-to-right 1 ... right-to-left
interactive
Boolean
false
true ... propagate interactions to overlay false ... ignore interactions
language
String
Empty
Language code (en, fr, es, de, ...)
custom1
String
Empty
Custom Parameter
custom2
String
Empty
Custom Parameter
custom3
String
Empty
Custom Parameter

setContent(content, callback)

Loads a Singular graphic into the overlay instance.
Attributes
Type
Required
Description
content
String or JSON
Yes
Content can be a string or an object and contain one of the values described below.
callback
Function
Yes
The callback function is called when content has been loaded.
Options to define the content:
Setting
Type
Default
Description
string
String
-
The composition revision URL.
compToken
String
-
The compositions token.
appOutputToken
String
-
The app output token.
webOutputToken
String
-
The web output token.
Sample
overlay.setContent(content, (params) => {
// called when content finished loading
});
Content options
// 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 Singular Composer
Composition revision URL

addListener(type, callback)

Adds a listener for events coming from the overlay.
Attributes
Type
Required
Description
type
String
Yes
An object containing one of the values described below.
callback
Function
Yes
The callback function for the type of event.
Values for listener type
Setting
Description
message
Listens to messages from interactive events and sends messages back to the video player.
error
Listen to errors reported by the overlay instance.
Sample: Listen to message from interactive events
overlay.addListener("message", (params) => {});
Sample: Listen to error reported by the Overlay Instance
overlay.addListener("error", (params) => {});

setDelay(delay)

Defines the delay for the execution of incoming graphics control commands.
Attributes
Type
Required
Description
delay
Number
Yes
Delay in milliseconds.
Sample
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()

Deletes the graphics overlay.

videoPlaying()

Notifies the overlay SDK that the video is playing.

videoPaused()

Notifies the overlay SDK that the video is paused.

videoBuffering()

Notifies the overlay SDK that the video is buffering.

videoStopped()

Notifies the overlay SDK that the video is stopped.

videoFinished()

Notifies the overlay SDK that the video is finished.

videoSeeking(time)

Notifies the overlay SDK that the video is seeking at a specific time. Time is in seconds.
Attributes
Type
Required
Description
time
Number
Yes
Time in seconds.
Sample
overlay.videoSeeking(500);

videoSeeked()

Notifies the overlay SDK that the seeking operation is finished.

videoTime(time)

Sends the current time of the video to the overlay SDK.
Attributes
Type
Required
Description
time
Number
Yes
Time in seconds.
Sample
overlay.videoTime(60.0);

videoMetadata(object)

Sends information about the video. This info can be received in the interactive layer code.
Attributes
Type
Required
Description
object
object
Yes
add description

videoMuted()

The user clicked the mute button in the video player.

videoUnmuted(value)

The user clicked the mute button in the video player again.
Attributes
Type
Required
Description
value
Number
Yes
The volume of the video.

videoVolume(value)

The user changed the volume of the video.
Attributes
Type
Required
Description
value
Number
Yes
The volume of the video.
Sample
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 received from the video that the overlay SDK can use to synchronize graphics to video. The format of time is Unix timestamp.
Attributes
Description
Type
Required
time
Time in the format of the UNIX timestamp
String
Yes
Sample
overlay.videoSegment(500);

message(object)

Send a message to the interactive layer.
Attributes
Type
Required
Description
object
object
Yes
Custom data as JSON object
Sample
overlay.message(object);