Javascript API documentation

Get Certified
Request Training
    Take full control of the 3D view and
    build the most advanced product experiences and configurator

    Emersya's comprehensive javascript API allows you to easily and seamlessly offer your own interfaces and unique ways of showcasing the products.

    You will be able to easily switch among available options, move from one viewpoint to another, listen to interactions coming from the 3D view, and so on.

    This is all you need to create the most amazing shopping experiences and there is no need for you to be an overskilled developer, you will be able to use Emersya's API even with basic knowledge of HTML and javascript.

    Example used in this documentation
    The configurable materials and material variations listed below will be used through all the examples in this API section.
    Configurable materials
    Material variations

    Best practises

    Grouping the API calls

    Always try to create your code in a way which groups the API calls.

    For example do not forget to :

    • Group the configurations in the same call to setMaterialsGroupConfigurations.
    • Group all the setMaterialByName calls in the same transaction or use setMaterialsByName.

    In case you cannot group them, it is very important to always wait the “onSuccess” event before making a new API call.

    Avoid mixing different configuration API calls

    Do not make a new configuration API call before receiving the “onSuccess” event of the previous call.

    For example:
    - Do not call a transaction at the same time as a setMaterialsGroupConfiguration.
    - Do not call a setMaterialsGroupConfiguration at the same time as a applyPreset.
    - Do not call a applyPreset at the same time as a transaction.

    • Do not call a transaction at the same time as a setMaterialsGroupConfiguration.
    • Do not call a setMaterialsGroupConfiguration at the same time as a applyPreset.
    • Do not call a applyPreset at the same time as a transaction.

    Updating custom elements

    The updateCustomTexture and updateCustomText instantaneously replace the texture in the viewer. It is possible to see the texture disappearing whilst the new one is loading.

    The best practice in this case is to do this update while the texture is not visible and to make it appear after the loading.

    Invoking API Functions

    Using an iframe

    Once the iframe has been embedded into the web page, you can use API functions directly from this page in order to take control over the 3D view and exchange information.

    To do this you first need to retrieve the DOM element which contains the iframe.

    viewerIframe = document.getElementById("emersyaIframe").contentWindow;

    You will then need to call the API via the postMessage function.

    For any call to the API, it is necessary to first call the registerCallback function.

    viewerIframe.postMessage({action : "registerCallback"}, "*");
    Using a script

    Once the script has been embedded into the web page, you can use API functions directly from this page in order to take control over the 3D view and exchange information.

    To do this you first need to retrieve the JS object representing the Emersya viewer.

    You can retrieve it from the moment you have received the 'emersyaViewerInitialized' event.

    document.addEventListener('emersyaViewerInitialized', function(){
      emersyaViewer = emViewers[VIEWER_CONTAINER_ID]
    }, false);

    Listening to API events

    Using an iframe

    The final step is to receive the data and response sent by the iframe. In order to receive the data, you will first be required to add an event listener to the “window” element of the parent site in which the iframe is embedded.

    Example : How to get the status of the 3D viewer while it is loading :

    window.addEventListener("message", function(event){
       if(event && event.data && event.data.action == " onStateChange "){
        // The data is accessible in the event.data object
      }
    }, false);
    Using a script

    The final step is to receive the data and response sent by the iframe. In order to receive the data, you need to add events listeners to the JS object for each event you want to handle.

    Example : How to get the status of the 3D viewer while it is loading :

    emersyaViewer.addEventListener("onStateChange", function(data){
        console.log(data);
    }, false);

    You will find the complete listenable event in the API events section.

    Quick Start

    Apply

    Turnkey app api

    Once the app iframe has been embedded into the web page, you can use API functions directly from this page in order to exchange information.

    To do this you first need to retrieve the DOM element which contains the iframe.

    viewerIframe = document.getElementById("emersyaIframe").contentWindow;

    You will then need to call the API via the postMessage function.

    For any call to the API, it is necessary to first call the registerCallback function.

    viewerIframe.postMessage({action : "registerCallback"}, "*");

    The final step is to receive the data and response sent by the iframe. In order to receive the data, you will first be required to add an event listener to the “window” element of the parent site in which the iframe is embedded.

    window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onStateChange"){} }, false);
    Events automatically sent by the app
    onStateChange

    This event is received when the 3D viewer changes state.
    The event to listen to is “onStateChange”.

    window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onStateChange"){} }, false);
    onConfigurationChange

    This event is received when the 3D viewer configuration change.
    The event to listen to is “onConfigurationChange”. It is accessible using event.data.action.
    Here, event.data will contain the current configuration of the configurated product

    window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onConfigurationChange"){} }, false);
    onConfigurationComplete

    This event is usually received when the user clicked on the “BUY” button of the app.
    The event to listen to is “onConfigurationComplete”. It is accessible using event.data.action.
    Here, event.data will contain the current configuration of the configurated product

    window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onConfigurationComplete"){} }, false);
    Features available through the API
    getViewerState

    To get the current viewer state, you have to listen to the “onStateChange” event.
    It is possible that the site which embeds the 3D viewer misses some events depending on how quickly it loads up in relation to Emersya’s 3D viewer.
    It is possible for the parent site to receive several events of the "loading" type. These events indicate the successive reception of data.

    viewerIframe.postMessage({action:"getViewerState"}, "*");
    setConfiguration

    This function allows you to set the configuration of a the configurable product.
    The configuration object is the same object as the one return by the “onConfigurationComplete” event.

    viewerIframe.postMessage({action:"setConfiguration", configuration : CONFIGURATION }, "*");
    getConfiguration

    This function allows you to retrieve the current configuration.
    To do it, you have to listen to the "onConfigurationComplete" event.

    viewerIframe.postMessage({action:"getConfiguration"}, "*");
    getScreenshot

    This function allows you to get a screenshot, the call is the same as the API one (https://emersya.com/en/api/getScreenshot)
    The event to listen to is "onScreenshot"

    viewerIframe.postMessage({action : 'getScreenshot', width : 512, height : 512 },'*');
    Error Handling

    It is necessary to listen to error messages sent out by the iframe in order to get information on the possible problems encountered by the 3D viewer.
    The event received in this case is “onError”.

    window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onError"){} }, false);

    Emersya's platform empowers brands to efficiently create, embed and share high-end interactive 3D product experiences and configurators for e-commerce and retail.

    Company
    Language
    English French
    Thanks! We will keep you up to date with our latest developments.
    By using Emersya you agree to the
    Terms & conditions