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.

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

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)

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)

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

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

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.

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

setConfig

Sets the configuration of an overlay.

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

setFrameNumber

This call has been depreciated.

videoCommand

This call has been depreciated.

PreviousReference NextComposition object

Last updated 2 years ago

Was this helpful?

SingularGraphics(domElement)

SDK properties

Return

SDK functions

addListener

Values for listener type

payload_changed

datanode_payload_changed

state_changed

message

error

getAdaptationGlobals

Return

See also

getCompositionById

Parameters

Return

See also

getCompositionInfo

Return

getConfig

Return

getMainComposition

Return

See also

getSequencer

Return

loadComposition

noTrack

onmessage

removeAllListener

See also

removeListener

Values for listener type

See also:

renderAppOutput

Sample

renderComposition

Sample

setAdaptationGlobals

See also

setConfig

setFrameNumber

videoCommand

Values for listener `type`

Values for listener `type`