Links

SDK functions

SingularGraphics(domElement)

Use the following code to create an instance of a Singular overlay:
const overlay = SingularGraphics("SingularOverlay");
Attributes
Type
Required
Description
domId
String
Yes
The target div that the SingularOverlay will replace.

SDK properties

Name
Type
Example
Description
host
String
"https://app.singular.live"
Domain of the SDK player client.
id
String
"SingularOverlay"
iframe ID.
const compMain = overlay.getMainComposition();
console.log("compMain =", compMain);

Return

object: Graphic SDK object
overlay:
> addListener: ƒ (event, callback)
> getAdaptationGlobals: ƒ ()
> getCompositionById: ƒ (compId)
> getCompositionInfo: ƒ ()
> getConfig: ƒ ()
> getMainComposition: ƒ ()
> getSequencer: ƒ ()
> host: "https://app.singular.live"
> id: "SingularOverlay"
> loadComposition: ƒ loadComposition(compositionId, cb)
> noTrack: ƒ ()
> onmessage: ƒ (e)
> removeAllListener: ƒ ()
> removeListener: ƒ (event, callback)
> renderAppOutput: ƒ renderAppOutput(appId, output, cb)
> renderComposition: ƒ renderComposition(compositionObject, cb)
> setAdaptationGlobals: ƒ setAdaptationGlobals(data)
> setConfig: ƒ (_config)
> setFrameNumber: ƒ setFrameNumber(frame)
> videoCommand: ƒ videoCommand(cmd, time)

SDK functions

The reference documentation provided in the following sections describes the Graphic SDK structure and methods.
Method
Return type
Description
-
Adds an event listener.
Object
Returns adaptation global parameters.
Object
Returns the composition object requested by its ID.
Object
Returns a detailed description of a composition's structure, control and data nodes, animation, and timeline states.
Object
Returns configuration details.
Object
Returns the main composition object.
Object
Returns the sequencer object.
-
Loads a composition defined by its ID or JSON URL.
noTrack()
-
Deactivates tracking of analytics.
-
Depreciated.
-
Removes all event listeners.
-
Removes an event listener defined by its name.
-
Loads a composition defined by its app ID.
-
Loads the composition defined in a composition object.
-
Sets adaptation global parameters.
-
Sets configuration properties.
-
Depreciated.
-
Depreciated.

addListener

Adds a listener for events coming from the overlay.
overlay.addListener(type, callback);
Attributes
Description
Type
Required
Text
type
A string containing one of the values described below
String
Yes
callback
The callback function for the type of event
Function
Yes

Values for listener type

Setting
Description
payload_changed
Listens to messages from control node updates.
datanode_payload_changed
Listens to messages from data node updates.
state_changed
Listens to messages for animation state changes.
message
Listens to messages from the interactive events and widgets.
error
Listens to errors reported by overlay instances.
See also:

payload_changed

Listens to payload_changed from control node updates.
overlay.addListener('payload_changed', (event, msg) => {
console.log("Composition payload changed:", event, msg);
});
Callback attributes
Attributes
Type
Description
event
String
The event name.
msg
Object
JSON data containing event details.
{
"compId": "your-composition-id",
"compName": "your-composition-name",
"compositionId": "your-composition-id",
"compositionName": "your-composition-name",
"payload": {
"your-control-node-ids": "your-control-node-values"
}
}

datanode_payload_changed

Listens to datanode_payload_changed from data node updates
overlay.addListener('datanode_payload_changed', (event, msg) => {
console.log("Composition datanode payload:", event, msg);
});
Callback attributes
Attributes
Type
Description
event
String
The event name.
msg
Object
JSON containing event details.
{
"id": "your-datanode-id",
"name": "your-datanode-name",
"payload": {
"your-datanode-ids": "your-datanode-values"
}
}

state_changed

Listens to state_changed for animation state changes.
overlay.addListener('state_changed', (event, msg) => {
console.log("Composition state changed:", event, msg);
});
Callback attributes
Attributes
Type
Description
event
String
The event name.
msg
Object
JSON containing event details.
{
"compositionId": "your-composition-id",
"compositionName": "your-composition-name",
"state": "In" | "Out" | "Out1" | "Out2"
}

message

Listens to message from interactive events and widgets
overlay.addListener('message', (event, msg) => {jaconsole.log("Composition message:", event, msg);
});
Callback attributes
Attributes
Type
Description
event
String
The event name.
msg
Object
JSON containing event details.
{
"event": "custom",
"params": {
"compId": "your-composition-id",
"id": "your-widget-id",
"name": "your-widget-name",
"widgetId": "widget-id",
"type": "type-of-message-sender",
"data": {
"JSON-object-with-custom-data"
}
}
}

error

Listens to error reported by an overlay instance.
overlay.addListener("error", (params) => {
console.log("Error:", params);
});
Callback attributes
Attributes
Type
Description
params
Object
JSON containing error details.

getAdaptationGlobals

Makes a request to get adaptation global settings.
const adaptationGlobals = overlay.getAdaptationGlobals();
console.log("adaptationGlobals =", adaptationGlobals);

Return

object: adaptation globals as a JSON object
{
"custom1": "",
"custom2": "",
"custom3": "",
"interactive": "interactive",
"language": "",
"layout": "landscape",
"screenSize": "small",
"textDirection": "ltr"
}

See also

getCompositionById

Returns the composition object requested by its ID.

Parameters

Name
Type
Description
compositionId
String
The ID of a composition.
const compositionId = "dbc46c1a-1375-4c2c-9f0d-1df5a86d0baf";
const compositionObject = overlay.getComposition(compositionId);
console.log("compositionObject =", compositionObject);

Return

object: Composition object
compositionObject:
> find: ƒ ()
> getCompositionById: ƒ (subCompId)
> getControlNode: ƒ ()
> getDataNodes: ƒ ()
> getLogicLayer: ƒ ()
> getModel: ƒ ()
> getPayload: ƒ ()
> getPayload2: ƒ ()
> getState: ƒ ()
> getSubcompositionById: ƒ (subCompId)
> id: "dbc46c1a-1375-4c2c-9f0d-1df5a86d0baf"
> jumpTo: ƒ (to)
> listSubcompositions: ƒ ()
> playTo: ƒ (to)
> seek: ƒ (to)
> sendMessage: ƒ (message)
> setPayload: ƒ (_payload)

See also

getCompositionInfo

Returns the JSON definition of the loaded composition.
const compositionInfo = overlay.getCompositionInfo();
console.log("compositionInfo =", compositionInfo);

Return

object: Composition object
{
"adaptationGlobals": {"screenSize": "small", "layout": "landscape", "textDirection": "ltr", "interactive": "interactive", "language": "",}
"compositionDuration": {"-N8o2dhQeHQXZ6Emr2I7": {}, "04234444-4383-4772-9619-ff971119eb5a": {},}
"compositionId": "-N8o2dhQeHQXZ6Emr2I7"
"compositionProps": {"logicLayers": {}, "timeline2Active": {}, "durations": {}}
"compositionStates": {"-Kn25RyfewL29LigHvV1": "Out1", "-KnXXbHZpD6sKVP4iHCD": "Out1", "-Knh0082CSZTy0CXJ_B_": "Out1",}
"dataSources": {"-N8o2dhQeHQXZ6Emr2I7": {}, "04234444-4383-4772-9619-ff971119eb5a": {},}
"effect": {"-N8o2dhQeHQXZ6Emr2I7": {}, "04234444-4383-4772-9619-ff971119eb5a": {},}
"idToName": {"04234444-4383-4772-9619-ff971119eb5a": "Panel Left - Image", "1c895c6d-f17d-400a-8591-0c38298bbb4f": "Fullscreen - Title",}
"nameToId": {"Panel Left - Image": "04234444-4383-4772-9619-ff971119eb5a", "Fullscreen - Title": "1c895c6d-f17d-400a-8591-0c38298bbb4f",}
"subcompositionNames": {"-N8o2dhQeHQXZ6Emr2I7": {}, "04234444-4383-4772-9619-ff971119eb5a": {},}
}

getConfig

Returns the configuration of the overlay.
const config = overlay.getConfig();
console.log("config =", config);

Return

object: JSON object

getMainComposition

Returns the composition object of the main or root composition.
const compMain = overlay.getMainComposition();
console.log("compMain =", compMain);

Return

object: Composition object
compMain:
> find: ƒ ()
> getCompositionById: ƒ (subCompId)
> getControlNode: ƒ ()
> getDataNodes: ƒ ()
> getLogicLayer: ƒ ()
> getModel: ƒ ()
> getPayload: ƒ ()
> getPayload2: ƒ ()
> getState: ƒ ()
> getSubcompositionById: ƒ (subCompId)
> id: "-N8o2dhQeHQXZ6Emr2I7"
> jumpTo: ƒ (to)
> listSubcompositions: ƒ ()
> playTo: ƒ (to)
> seek: ƒ (to)
> sendMessage: ƒ (message)
> setPayload: ƒ (_payload)

See also

getSequencer

Returns the sequencer object of the overlay.
const sequencer = overlay.getSequencer();
console.log("sequencer =", sequencer);

Return

object: Sequencer object
sequencer:
> play: ƒ (time)
> seek: ƒ (time)
> seqId: "-N8o2dhQeHQXZ6Emr2I7"
> setDuration: ƒ (duration)
> setPayload: ƒ (payload)
> start: ƒ ()
> stop: ƒ ()
See also

loadComposition

Loads a composition into an overlay instance.
overlay.loadComposition(composition, outputName, callback);
Attributes
Type
Required
Description
composition
String
Yes
A composition referenced by token or URL.
outputName
String
Yes
Depreciated. Set output name to null for compatibility reasons.
callback
Function
Yes
Callback function called when the content has been loaded.
Sample
Load by composition URL
Load by composition token
const compositionUrl = "https://assets.singular.live/f12f184c9a0eb763beb40478e02a1250/jsons/164gBjjETnHFKEU3LjPCKe.json";
overlay.loadComposition(compositionUrl, null, (success) => {
// called when content finished loading
if (success) {
console.log("Composition loaded");
} else {
console.warn("Couldn't load composition");
}
});
const compositionToken = "08EBsfeF4yoYLejOXM51Rk";
overlay.loadComposition(compositionToken , null, (success) => {
// called when content finished loading
if (success) {
console.log("Composition loaded");
} else {
console.warn("Couldn't load composition");
}
});

noTrack

Deactivates analytic tracking.

onmessage

This call has been depreciated.

removeAllListener

Removes all registered listeners.
overlay.removeAllListener();

See also

removeListener

Removes a listener specified by its type.
overlay.removeListener(type, callback);
Attributes
Type
Required
Description
type
String
Yes
A string containing one of the values described below.
callback
Function
Yes
The callback function for the type of event.

Values for listener type

Setting
Description
payload_changed
Listens to messages from control node updates.
datanode_payload_changed
Listens to messages from data node updates.
state_changed
Listens to messages for animation state changes.
message
Listens to messages from the interactive events and widgets.
error
Listens to errors reported by an overlay instance.

See also:

renderAppOutput

Load san app output into the overlay instance.
overlay.renderAppOutput(appInstanceId, outputName, callback);
Attributes
Type
Required
Description
appInstanceId
String
Yes
The ID of an app instance.
outputName
String
Yes
Depreciated. Sets output name to null for compatibility reasons.
callback
Function
Yes
The callback function called when the content has been loaded.

Sample

const appInstanceId = 12345;
overlay.renderAppOutput(appInstanceId, null, (success) => {
// called when content finished loading
if (success) {
console.log("App output loaded");
} else {
console.warn("Couldn't load app output");
}
});

renderComposition

Loads a composition into an overlay instance.
overlay.renderComposition(composition, callback);
Attributes
Type
Required
Description
composition
Object
Yes
A composition's JSON object.
callback
Function
Yes
The callback function called when the content has been loaded.

Sample

const composition = {...};
overlay.renderComposition(composition, null, (success) => {
// called when content finished loading
if (success) {
console.log("Composition loaded");
} else {
console.warn("Couldn't load composition");
}
});

setAdaptationGlobals

Sets adaptation global settings.
const adaptationGlobals = {
"custom1": "stationId=abc123",a
"custom2": "",
"custom3": "",
"interactive": "",
"language": "",
"layout": "portrait",
"screenSize": "small",
"textDirection": "ltr"
};
overlay.setAdaptationGlobals(adaptationGlobals);

See also

setConfig

Sets the configuration of an overlay.
const config = {...};
overlay.setConfig(config);

setFrameNumber

This call has been depreciated.

videoCommand

This call has been depreciated.