• Experience-level commands

  • Page-level commands

  • Layer-level commands

  • SyncedObject-level commands

  • Component-level commands

  • Events

SDK Documentation

Software Development Kit v5

  • Experience-level commands

    • getTitle

      called on: CerosExperience arguments: none

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

       
      var experienceTitle = experience.getTitle();

    • getCurrentPage()

      called on: CerosExperience arguments:  none

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

       
      var page = experience.getCurrentPage();

    • getAllPages()

      called on: CerosExperience arguments: none

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

       
      var userId = experience.getCurrentUserId();

    • getAllPages

      called on: CerosExperience arguments: none

      Returns a CerosPageCollection representing all the pages of the experience.

       
      var pageCollection = experience.getAllPages();
var thirdPage = pageCollection.pages[2];
thirdPage.disable();

    • 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.

       
      var myPage = experience.findPageById('a-page-id');
if (myPage){
    myPage.disable(); //disables the page, if it was 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.

       
      var taggedPages = experience.findPagesByTag("foo");

    • 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.

       
      experience.goToPage(3);

    • 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.

       
      experience.goToNextPage();

    • 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.

       
      experience.goToPreviousPage();

    • findAllSyncedObjects()

      called on: CerosExperience arguments: none

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

       
      var syncedObjects = experience.findAllSyncedObjects();
syncedObjects.show(); //shows all syncedObjects in the experience

    • 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.

       
      var mySyncedObject = experience.findSyncedObjectById('a-syncedObject-id');
if (mySyncedObject){
    mySyncedObject.hide(); //hides the syncedObject, if it was 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.

       
      var taggedSyncedObjects = experience.findSyncedObjectsByTag("foo");

    • 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.

       
      var taggedSyncedObjects = experience.findSyncedObjectsWithAnyTags(["foo","bar"]);

    • 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.

       
      var taggedSyncedObjects = experience.findSyncedObjectsWithAllTags(["foo","bar"]);

    • 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.

       
      var layers = experience.findAllLayers();
layers.show(); //shows all layers in the experience

    • 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.

       
      var myLayer = experience.findLayerById('a-layer-id');
if (myLayer){
    myLayer.hide(); //hides the layer, if it was found
}

    • 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.

       
      var taggedLayers = experience.findLayersByTag("foo");

    • 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.

       
      var layers = experience.findAllComponents();
components.show(); //shows all components in the experience

    • 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.

       
      var component = experience.findComponentById('a-component-id');

    • 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.

       
      var taggedComponents = experience.findComponentsByTag("foo");

    • 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.

       
      var taggedComponents = experience.findComponentsWithAnyTags(["foo","bar"]);

    • 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

       
      var pageChangedCallback = function(page){
  var payload = page.getPayload();
}
experience.on(CerosSDK.EVENTS.PAGE_CHANGED, pageChangedCallback);

      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.

       
      experience.setUserConsentForAnalytics(true);

    • 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.

       
      myExperience.getUserConsentForAnalytics(function(consent) {
  switch (consent) {
    case 'Consented':
      // Do something if the user has consented
      break;

    case 'Declined':
      // Do something if the user has declined
      break;

    case 'Unknown':
      // Do something if the user has not made a selection
      break;
  }
});

  • 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.

       
      var thePage = experience.findPagesByTag('page-to-disable');
thePage.disable();

    • 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.

       
      var thePage = experience.findPagesByTag('page-to-enable');
thePage.enable();

    • findAllLayers()

      called on: CerosPage arguments: none

      Returns a CerosLayerCollection containing all the layers in the page.

       
      var myPage = experience.getCurrentPage();
var layers = myPage.findAllLayers();
layers.show(); //shows all layers on current page

    • findAllSyncedObjects()

      called on: CerosPage arguments: none

      Returns a CerosSyncedObjectCollection containing all the syncedObjects in the page.

       
      var myPage = experience.getCurrentPage();
var syncedObjects = myPage.findAllSyncedObjects();
syncedObjects.show(); //shows all syncedObjects on current 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
       
      if (myPage.getPageState() === CerosSDK.PAGESTATE.DISABLED){
  myPage.enable();
}

    • 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.

       
      experience.getCurrentPage().startAnimations();

    • pauseAnimations()

      called on: CerosPage arguments: none

      Pauses all entry animations on the page.

       
      experience.getCurrentPage().pauseAnimations();

    • 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.

       
      var myPayload = experience.getCurrentPage().getPayload();

    • 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.

       
      var tags = experience.getCurrentPage().getTags();

    • getWidth()

      called on: CerosPage arguments: none

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

       
      var pageWidth = experience.getCurrentPage().getWidth();

    • getHeight()

      called on: CerosPage arguments: none

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

       
      var pageHeight = experience.getCurrentPage().getHeight();

    • getPageNumber()

      called on: CerosPage arguments: none

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

       
      var currentPageNumber = experience.getCurrentPage().getPageNumber();

    • findAllComponents()

      called on: CerosPage or CerosPageCollection arguments: none

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

       
      var components = experience.findPagesByTag('my-page-tag').findAllComponents();

  • Layer-level commands

    • findAllComponents()

      called on: CerosLayer arguments: none

      Returns a CerosComponentCollection containing the components in the CerosLayer.

       
      var components = myLayer.findAllComponents();
components.click(); //clicks all components in the first layer

    • 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.

       
      var myLayer = myExperience.findLayerById('a-layer-id');
myLayer.show();

    • 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.

       
      var myLayer = myExperience.findLayerById('a-layer-id');
myLayer.hide();

    • getPage()

      called on: CerosLayer arguments: none

      Retrieves the CerosPage that this layer belongs to.

       
      var myPage = myExperience.findLayerById('a-layer-id').getPage();

    • 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.

       
      var myPayload = myExperience.findLayerById('a-layer-id').getPayload();

    • 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.

       
      var tags = myExperience.findLayerById('a-layer-id').getTags();

    • isComponent()

      called on: CerosLayer arguments: none

      Returns true if the layer is a component or group

       
      var myLayer = myExperience.findLayerById('a-layer-id');
if (myLayer.isComponent()) {
    myLayer.show();
}

    • isGroup()

      called on: CerosLayer arguments: none

      Returns true if the layer is a group

       
      var myLayer = myExperience.findLayerById('a-layer-id');
if (myLayer.isGroup()) {
    myLayer.show();
}

    • isSyncedObject()

      called on: CerosLayer arguments: none

      Returns true if the layer is a synced object

       
      var myLayer = myExperience.findLayerById('a-layer-id');
if (myLayer.isSyncedObject()) {
    myLayer.show();
}

    • isFolder()

      called on: CerosLayer arguments: none

      Returns true if the layer is a folder

       
      var myLayer = myExperience.findLayerById('a-layer-id');
if (myLayer.isFolder()) {
    myLayer.show();
}

    • 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

  • 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.

       
      var layers = mySyncedObject.findAllLayers();
layers.hide(); // hides all layers in 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.

       
      var mySyncedObject = experience.findSyncedObjectById('a-syncedObject-id');
mySyncedObject.click();

    • 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.

       
      var myComponent = experience.findComponentById('a-component-id');
myComponent.click();

    • 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.

       
      var myImage = experience.findComponentById('an-image-id');
var url = myComponent.getFullResolutionUrl();

    • getWidth()

      called on: CerosComponent arguments: none

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

       
      var componentWidth = experience.findComponentById('a-component-id').getWidth();

    • getHeight()

      called on: CerosComponent arguments: none

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

       
      var componentHeight = experience.findComponentById('a-component-id').getHeight();

    • getX()

      called on: CerosComponent arguments: none

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

       
      var componentX = experience.findComponentById('a-component-id').getX();

    • getY()

      called on: CerosComponent arguments: none

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

       
      var componentY = experience.findComponentById('a-component-id').getY();

    • 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.

       
      experience.findComponentById('a-component-id').reset();

    • 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.

       
      experience.findComponentById('an-image-component-id').setUrl('www.example.com/example.jpg', true);

    • 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

       
      var taggedComponents = componentCollection.findComponentsByTag("foo");

    • 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.

       
      var myVideoComponent = experience.findComponentById('a-video-component-id');
myVideoComponent.startVideo();

    • 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.

       
      var myVideoComponent = experience.findComponentById('a-video-component-id');
myVideoComponent.stopVideo();

    • 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.

       
      var myTextComponent = experience.findComponentById('a-text-component-id');
myTextComponent.setText("I like tacos!");

  • 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.

       
      var pageChangedCallback = function(page){
  var payload = page.getPayload();
}
experience.on(CerosSDK.EVENTS.PAGE_CHANGED, pageChangedCallback);

    • 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.

       
      var pageChangingCallback = function(page){
  var payload = page.getPayload();
}
experience.on(CerosSDK.EVENTS.PAGE_CHANGING, pageChangingCallback);

    • 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.

       
      var componentClickedCallback = function(component){
  component.hide();
}
experience.on(CerosSDK.EVENTS.CLICKED, componentClickedCallback);

    • 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.

       
      var layerShownCallback = function(layer){
  var payload = layer.getPayload();
}
experience.on(CerosSDK.EVENTS.SHOWN, layerShownCallback);

    • 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.

       
      var layerHiddenCallback = function(layer){
  var payload = layer.getPayload();
}
experience.on(CerosSDK.EVENTS.HIDDEN, layerHiddenCallback);

    • 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
       
      var socialShareCallback = function(component, shareType){
  if (shareType === CerosSDK.SHARING_TYPES.FACEBOOK){
    component.hide();
  }
}
experience.on(CerosSDK.EVENTS.SOCIAL_SHARE, socialShareCallback);

    • 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.

       
      var animationStartedCallback = function(component){
  var payload = component.getPayload();
}
experience.on(CerosSDK.EVENTS.ANIMATION_STARTED, animationStartedCallback);

    • 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.

       
      var animationEndedCallback = function(component){
  var payload = component.getPayload();
}
experience.on(CerosSDK.EVENTS.ANIMATION_ENDED, animationEndedCallback);

    • 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.

       
      var videoPlayedCallback = function(component){
  var payload = component.getPayload();
}
experience.on(CerosSDK.EVENTS.VIDEO_PLAYED, videoPlayedCallback);