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
addListener(event, callback)	-	Adds an event listener.
getAdaptationGlobals()	Object	Returns adaptation global parameters.
getCompositionById(compId)	Object	Returns the composition object requested by its ID.
getCompositionInfo()	Object	Returns a detailed description of a composition's structure, control and data nodes, animation, and timeline states.
getConfig()	Object	Returns configuration details.
getMainComposition()	Object	Returns the main composition object.
getSequencer()	Object	Returns the sequencer object.
loadComposition(compositionId, callback)	-	Loads a composition defined by its ID or JSON URL.
noTrack()	-	Deactivates tracking of analytics.
onmessage(event)	-	Depreciated.
removeAllListener()	-	Removes all event listeners.
removeListener(event, callback)	-	Removes an event listener defined by its name.
renderAppOutput(appId, output, callback)	-	Loads a composition defined by its app ID.
renderComposition(compositionObject, callback)	-	Loads the composition defined in a composition object.
setAdaptationGlobals(data)	-	Sets adaptation global parameters.
setConfig(data)	-	Sets configuration properties.
setFrameNumber(frame)	-	Depreciated.
videoCommand(cmd, time)	-	Depreciated.

addListener

Adds a listener for events coming from the overlay.

overlay.addListener(type, callback);

Attributes	Description	Type	Required
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:

removeAllListener removeListener

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

setAdaptationGlobals

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

Composition object

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

Composition object

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

Sequencer object

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

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

Load by composition token

noTrack

Deactivates analytic tracking.

onmessage

This call has been depreciated.

removeAllListener

Removes all registered listeners.

overlay.removeAllListener();

See also

addListener

removeListener

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:

removeAllListener removeListener

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

getAdaptationGlobals

setConfig

Sets the configuration of an overlay.

const config = {...};
overlay.setConfig(config);

setFrameNumber

This call has been depreciated.

videoCommand

This call has been depreciated.