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

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

SettingTypeDefaultDescription

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.

SettingTypeDefaultDescription

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.

AttributesTypeRequiredDescription

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:

SettingTypeDefaultDescription

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

addListener(type, callback)

Adds a listener for events coming from the overlay.

AttributesTypeRequiredDescription

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

SettingDescription

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.

AttributesTypeRequiredDescription

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.

AttributesTypeRequiredDescription

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.

AttributesTypeRequiredDescription

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.

AttributesTypeRequiredDescription

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.

AttributesTypeRequiredDescription

value

Number

Yes

The volume of the video.

videoVolume(value)

The user changed the volume of the video.

AttributesTypeRequiredDescription

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.

AttributesDescriptionTypeRequired

time

Time in the format of the UNIX timestamp

String

Yes

Sample

overlay.videoSegment(500);

message(object)

Send a message to the interactive layer.

AttributesTypeRequiredDescription

object

object

Yes

Custom data as JSON object

Sample

overlay.message(object);

Last updated