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);