Software Development Kit v5

Experience-level commands

getTitle

called on: CerosExperience arguments: none

Returns a string that contains the title of the ceros experience.

getCurrentPage()

called on: CerosExperience arguments:  none

Returns a CerosPage representing only the current page of the experience.

getAllPages()

called on: CerosExperience arguments: none

Returns the ID of the current user viewing the experience as a string.

getAllPages

called on: CerosExperience arguments: none

Returns a CerosPageCollection representing all the pages of the experience.

findPageById(pageId)

called on: CerosExperience arguments: pageId – the SDK ID of the page to retrieve

Returns a CerosPage representing either the single page that has ID pageId, or null if the ID can not be found.

findPagesByTag(tag)

called on: CerosExperience arguments: tag – a string

Returns a CerosPageCollection containing all pages in the experience that have been tagged with tag in the Studio.

goToPage(pageNum)

called on: CerosExperience arguments: pageNum – The number of the page to go to. Must be between 1 and the total number of pages in the experience, inclusive.

Navigates the experience to the page specified by pageNum. If pageNum is not a valid page in the experience, the command will do nothing.

goToNextPage()

called on: CerosExperience arguments: none

Navigates the experience to the page directly after the one the user is currently on. If the user is on the last page (if the experience is not a carousel), or if the experience only has one page, the command will do nothing.

goToPreviousPage()

called on: CerosExperience arguments: none

Navigates the experience to the page directly before the one the user is currently on. If the user is on the first page (if the experience is not a carousel), or if the experience only has one page, the command will do nothing.

findAllSyncedObjects()

called on: CerosExperience arguments: none

Returns a CerosSyncedObjectCollection. All syncedObjects in the experience are returned.

findSyncedObjectById(syncedObjectId)

called on: CerosExperience arguments: syncedObjectId – the SDK ID of the syncedObject to retrieve

Returns a CerosSyncedObject representing either the single syncedObject that has ID syncedObjectId, or null if the ID can not be found.

findSyncedObjectsByTag(tag)

called on: CerosExperience arguments: tag – a string

Returns a CerosSyncedObjectCollection containing all syncedObjects in the experience that have been tagged with tag in the Studio.

findSyncedObjectsWithAnyTags(tags)

called on: CerosExperience arguments: tags – an array of strings

Returns a CerosSyncedObjectCollection containing all syncedObjects tagged with any of the tags passed in the tags array in the studio.

findSyncedObjectsWithAllTags( tags )

called on: CerosExperience arguments: tags – an array of strings

Returns a CerosSyncedObjectCollection containing all syncedObjects tagged with all of the tags passed in the tags array in the studio.

findAllLayers()

called on: CerosExperience arguments: none

Returns a CerosLayerCollection. All layers in the experience are returned.

This includes layers within syncedObjects. Commands run on layers within syncedObjects apply to all uses of the syncedObject.

findLayerById( layerId )

called on: CerosExperience arguments: layerId – the SDK ID of the layer to retrieve

Returns a CerosLayer representing either the single layer that has ID layerId, or null if the ID can not be found.

This will also fetch layers within syncedObjects by their SDK ID. Commands run on layers within syncedObjects apply to all uses of the syncedObject.

findLayersByTag( tag )

called on: CerosExperience arguments: tag – a string

Returns a CerosLayerCollection containing all layers in the experience that have been tagged with tag in the Studio.

This includes layers within syncedObjects. Commands run on layers within syncedObjects apply to all uses of the syncedObject.

findAllComponents()

called on: CerosExperience arguments: none

Returns a CerosComponentCollection. All components in the experience are returned.

This includes components within syncedObjects. Commands run on components within syncedObjects apply to all uses of the syncedObject.

findComponentById( component-id )

called on: CerosExperience arguments: component-id – the SDK ID of the component to retrieve

Returns a CerosComponent that represents the component with ID component-id. If there is no component with this ID, the command will return null.

This will also fetch components within syncedObjects by their SDK ID. Commands run on components within syncedObjects apply to all uses of the syncedObject.

findComponentsByTag( tag )

called on: CerosExperience arguments: tag – a string

Returns a CerosComponentCollection containing all components in the experience that have been tagged with tag in the Studio.

This includes components within syncedObjects. Commands run on components within syncedObjects apply to all uses of the syncedObject.

findComponentsWithAnyTags( tags )

called on: CerosExperience arguments: tags – an array of strings

Returns a CerosComponentCollection containing all components tagged with any of the tags passed in the tags array in the studio.

This includes components within syncedObjects. Commands run on components within syncedObjects apply to all uses of the syncedObject.

on(eventName, callback)

called on: CerosExperience arguments: eventName – The name of the event to subscribe to callback – The function to run when this event is received

See Events

setUserConsentForAnalytics(consent)

called on: CerosExperience arguments: consent – User consent (true/false)

Sends the user consent selection to the experience, which will save the user’s consent selection and enable or disable tracking cookies. This function does not return anything.

getUserConsentForAnalytics( callback )

called on: CerosExperience arguments: callback – Function to be called with the user consent value. This is a string with one of the following values:

“Consented” – When the user specifically consented to analytics tracking. “Declined” – When the user specifically declined analytics tracking. “Unknown” – When the user has not made a selection.

This function does not return anything, the consent value is passed to the callback.

Page-level commands

disable()

called on: CerosPage or CerosPageCollection arguments: none

Disables the page(s) in the Ceros experience. When a page is disabled, it will not be able to be navigated to. If the page is the current page the user is viewing, or if the page is already disabled, the command will do nothing.

enable()

called on: CerosPage or CerosPageCollection arguments: none

Enables the page(s) in the Ceros experience. If the page is already enabled, the command will do nothing.

findAllLayers()

called on: CerosPage arguments: none

Returns a CerosLayerCollection containing all the layers in the page.

findAllSyncedObjects()

called on: CerosPage arguments: none

Returns a CerosSyncedObjectCollection containing all the syncedObjects in the page.

getPageState()

called on: CerosPage arguments: none

Returns a CerosSDK.PAGESTATE constant representing the current state of the page. The return value will be one of:

• CerosSDK.PAGESTATE.ENABLED – the page is loaded and enabled
• CerosSDK.PAGESTATE.DISABLED – the page is loaded but has been disabled in the experience

startAnimations()

called on: CerosPage arguments: none

Starts all entry animations on the page. If the animation is already animating it will be restarted from the beginning.

pauseAnimations()

called on: CerosPage arguments: none

Pauses all entry animations on the page.

getPayload()

called on: CerosPage arguments: none

Retrieves the payload for the page, if you have configured one in the Studio. If there is not a payload configured, this will return undefined.

getTags()

called on: CerosPage arguments: none

Retrieves the tags for the page, if you have tagged it with any in the Studio. If the page has not been tagged, then an empty array is returned.

getWidth()

called on: CerosPage arguments: none

Retrieves the width of the page as configured in the Studio.

getHeight()

called on: CerosPage arguments: none

Retrieves the height of the page as configured in the Studio.

getPageNumber()

called on: CerosPage arguments: none

Retrieves the 1-based index of the page as configured in the Studio.

findAllComponents()

called on: CerosPage or CerosPageCollection arguments: none

Retrieves a CerosComponentCollection containing all the components on the CerosPage or pages inside the CerosPageCollection.

Layer-level commands

findAllComponents()

called on: CerosLayer arguments: none

Returns a CerosComponentCollection containing the components in the CerosLayer.

show()

called on: CerosLayer or CerosLayerCollection arguments: none

Makes the layer(s) visible. If this is called on a layer that is already visible, it will have no effect. Any entry animations configured on components in this layer will be triggered.

hide()

called on: CerosLayer or CerosLayerCollection arguments: none

Hides the layer(s). If this is called on a layer that is already hidden, it will have no effect. Any exit animations configured on components in this layer will be triggered.

getPage()

called on: CerosLayer arguments: none

Retrieves the CerosPage that this layer belongs to.

getPayload()

called on: CerosLayer arguments: none

Retrieves the payload for the layer, if you have configured one in the Studio. If there is not a payload configured, this will return undefined.

getTags()

called on: CerosLayer arguments: none

Retrieves the tags for the layer, if you have tagged it with any in the Studio. If the layer has not been tagged, then an empty array is returned.

isComponent()

called on: CerosLayer arguments: none

Returns true if the layer is a component or group

isGroup()

called on: CerosLayer arguments: none

Returns true if the layer is a group

isSyncedObject()

called on: CerosLayer arguments: none

Returns true if the layer is a synced object

isFolder()

called on: CerosLayer arguments: none

Returns true if the layer is a folder

• on(eventName, callback)

  called on: CerosLayer or CerosLayerCollection arguments: eventName – The name of the event to subscribe to callback – The function to run when this event is received

• merge(layerCollections)

  called on: CerosLayerCollection arguments: layerCollections – An array of CerosLayerCollections to merge

  See Events

See Events

SyncedObject-level commands

• Methods Inherited from CerosLayer:

  • findAllComponents()

    • Returns a CerosComponentCollection of all components in the CerosSyncedObject
  • getPayload()
  • getTags()
  • getPage()
  • isComponent()
  • isSyncedObject()
  • isGroup()
  • isFolder()
  • show()
  • hide()
  • on

• Methods Inherited from CerosLayerCollection:

  • show()
  • hide()
  • on()
  • merge()

• findAllLayers()

  called on: CerosSyncedObject, CerosSyncedObjectCollection arguments: none

  Returns a CerosLayerCollection containing the components in the CerosSyncedObject. If called on a CerosSyncedObjectCollection, this method will return all unique layers in all the syncedObjects in the collection. Important note: Commands run on layers returned from this method affect the layers in all uses of the syncedObject.

click()

called on: CerosSyncedObject or CerosSyncedObjectCollection arguments: none

Simulates a click event on the syncedObject(s) that this is called on. This is equivalent to the user clicking the syncedObject(s), and all events/animations that would be triggered by a user clicking the syncedObject(s) will also be triggered by calling this method.

• on(eventName, callback)

  called on: CerosSyncedObject arguments: eventName – The name of the event to subscribe to callback – The function to run when this event is received

  See Events

Component-level commands

• Methods Inherited from CerosLayer:

  • findAllComponents()

    • If the component is a group, returns all components in the group, otherwise returns an empty CerosComponentCollection
  • getPayload()
  • getTags()
  • getPage()
  • isComponent()
  • isSyncedObject()
  • isGroup()
  • isFolder()

  • show()

    • Please note: Any components that are configured in the Studio to be initially hidden will not be able to be shown via this command. However, you can use show() and hide() on a folder that contains the component to make it visible.
  • hide()
  • on

• Methods Inherited from CerosLayerCollection:

  • show()
  • hide()
  • on()
  • merge()

click()

called on: CerosComponent or CerosComponentCollection arguments: none

Simulates a click event on the component(s) that this is called on. This is equivalent to the user clicking the component(s), and all events/animations that would be triggered by a user clicking the component(s) will also be triggered by calling this method.

getFullResolutionUrl()

called on: CerosComponent arguments: none

If the CerosComponent is a scalar image, returns the URL of the full-resolution version of the image. If it is not an image, returns undefined.

getWidth()

called on: CerosComponent arguments: none

Retrieves the unscaled width of the component (the width as configured in the Studio).

getHeight()

called on: CerosComponent arguments: none

Retrieves the unscaled height of the component (the height as configured in the Studio).

getX()

called on: CerosComponent arguments: none

Retrieves the x position of the component after any entry animations have finished playing.

getY()

called on: CerosComponent arguments: none

Retrieves the y position of the component after any entry animations have finished playing.

reset()

called on: CerosComponent or CerosComponentCollection arguments: none

If called on a text component, resets the text content of that component back to the original text content provided in the studio. If called on an image component, resets the src of the image back to the original URL provided in the studio. If called on a CerosComponentCollection, will reset any text or image components in the collection.

setUrl()

called on: CerosComponent arguments: url – The url of the new image useNewImageSize – Weather to load the new image in at its full size or to scale it to the size of the old image.

If the component is an image, sets the src of the image to the url provided. Has no effect if called on a component that is not an image.

on(eventName, callback)

called on: CerosComponent or CerosComponentCollection arguments: eventName – The name of the event to callback – The function to run when this event is received

See Events

findComponentsByTag( tag )

called on: CerosComponentCollection arguments: tag – a string

Returns a CerosComponentCollection containing all components in the collection that have been tagged with tag in the Studio

startVideo()

called on: CerosComponent or CerosComponentCollection arguments: none

Starts video playback on the video component(s). Calling this on a component that is not a video will have no effect. Calling this on a video that is already playing will restart it from the beginning.

stopVideo()

called on: CerosComponent or CerosComponentCollection arguments: none

Pauses video playback on the video component(s). Calling this on a component that is not a video will have no effect. Calling this on a video that is not already playing will have no effect.

setText()

called on: CerosComponent or CerosComponentCollection arguments: textContext – The new text to display in the text component

Sets the displayed text content on the text component(s). Calling this on a component that is not a text component will have no effect.

Please note: This will not cause the text component to resize. Components will need to be sized properly to fit any text set on them or the text will be cut off.

Events

Page Changed

event constant: CerosSDK.EVENTS.PAGE_CHANGED can be subscribed on: CerosExperience callback arguments: page – CerosPage the new page

Fired whenever a page change has completed in a Ceros experience.

Page changing

event constant: CerosSDK.EVENTS.PAGE_CHANGING can be subscribed on: CerosExperience callback arguments: page – CerosPage the new page

Fired whenever a page STARTS to change in a Ceros experience. Note that issuing a getCurrentPage command will return the page being navigated FROM until the page transition is complete.

Clicked

event constant: CerosSDK.EVENTS.CLICKED can be subscribed on:  CerosExperience,  CerosComponent,  CerosComponentCollection,  CerosSyncedObject  or  CerosSyncedObjectCollection  callback arguments: component –  a CerosComponent  or  CerosSyncedObject   representing the component or syncedObject that was clicked

Fired whenever a component is clicked in the experience.

Layer shown

event constant: CerosSDK.EVENTS.SHOWN can be subscribed on:  CerosExperience,  CerosLayer,  CerosLayerCollection,  CerosComponent,  CerosComponentCollection,  CerosSyncedObject  or  CerosSyncedObjectCollection  callback arguments: layer – a CerosLayer representing the layer that was made visible

Fired whenever a layer is shown (from being previously hidden) in the experience.

Layer hidden

event constant: CerosSDK.EVENTS.HIDDEN can be subscribed on:  CerosExperience,  CerosLayer,  CerosLayerCollection,  CerosComponent,  CerosComponentCollection, CerosSyncedObject  or  CerosSyncedObjectCollection  callback arguments: layer – a CerosLayer representing the layer or syncedObject that was hidden

Fired whenever a layer is hidden (from being previously visible) in the experience.

Social share

event constant: CerosSDK.EVENTS.SOCIAL_SHARE can be subscribed on:  CerosExperience,  CerosComponent,  CerosComponentCollection,  CerosSyncedObject  or  CerosSyncedObjectCollection  callback arguments: component – a  CerosComponent  or CerosSyncedObject  representing the component or syncedObject that triggered the social share shareType – a CerosSDK.SHARING_TYPE  constant representing the type of social sharing that happened

Fired whenever the user performs a social sharing action. shareType will be one of these constants:

• CerosSDK.SHARING_TYPES.FACEBOOK
• CerosSDK.SHARING_TYPES.TWITTER
• CerosSDK.SHARING_TYPES.PINTEREST
• CerosSDK.SHARING_TYPES.EMAIL

Animation started

event constant: CerosSDK.EVENTS.ANIMATION_STARTED can be subscribed on:  CerosExperience,  CerosComponent,  CerosComponentCollection,  CerosSyncedObject  or CerosSyncedObjectCollection  callback arguments: component – a  CerosComponent  or CerosSyncedObject  representing the component or syncedObject that an animation started playing on

Fired whenever an animation is triggered.

In SDK version 4.0.0 and above, when an animation is configured to repeat, this event will fire only on the first iteration of that animation.

Animation ended

event constant: CerosSDK.EVENTS.ANIMATION_ENDED can be subscribed on:  CerosExperience,  CerosComponent,  CerosComponentCollection,  CerosSyncedObject  or  CerosSyncedObjectCollection  callback arguments:  component –   a CerosComponent  or  CerosSyncedObject  representing the component syncedObject that an animation finished playing on

Fired whenever an animation completes.

Video Played

event constant: CerosSDK.EVENTS.VIDEO_PLAYED can be subscribed  on:  CerosExperience  or CerosComponent or   CerosComponentCollection  callback arguments:component  – a CerosComponent  representing the component that started playing

Fired whenever a video starts playing.