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

    Before starting to interact with the app, you will first need to initialize the API with the following call.

    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.
    The following example show you how to retrieve the status of the 3D viewer.

    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 "){
        // [string] The data is accessible in the event.data object
      }
    }, false);

    You can stop listening to the viewer events. You can do it by removing the event listener to the "window" element of the parent site in which the iframe is embedded

    Example : How to unlisten events from the viewer :

    window.removeEventListener("message", function(event){
       if(event && event.data && event.data.action == " onStateChange "){
        // [string] 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);
    });

    You can stop listening to the viewer events. You can do it by removing the event listener to the JS object

    Example : How to unlisten to the "onStateChange" event

    emersyaViewer.removeEventListener("onStateChange");

    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

    Before starting to interact with the app, you will first need to initialize the API with the following call.

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

    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.
    The following example show you how to retrieve the status of the 3D viewer.

    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. You may want to listen to this event in order to know when the viewer is ready to be used.
    The event to listen to is “onStateChange”

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

    The received event data parameter will contains the following data

    {
    	action: "onStateChange"
    	state: {
    		arCompatibility : true,     // [boolean] True if the AR is available on the device, false otherwise,
    		arState         : "",       // [string]  State of the AR,
    		loadingProgress : 1,        // [float]   Loading progress for the 3D viewer,
    		viewerState     : "loaded", // [string]  Viewer state among opened | ready | started | loading | loaded| 3dlost | stopped | fallbackloaded,
    		viewerType      : "webgl",  // [string]  Type of the viewer among null| webgl | fallback,
    		webglStatus     : "65536",  // [integer] Viewer’s webgl status,
    		version: {
    			actualProject           : 1,     // [integer] Loaded project version number,
    			actualViewer            : 1,     // [integer] Loaded viewer version number,
    			loadedFromConfiguration : false, // [boolean] Define if the viewer has been loaded from a existing configuration,
    			routeProject            : 1,     // [integer] Most recent project version number,
    			routeViewer             : 1,     // [integer] Most recent viewer version number,
    		}
    	}
    }
    onConfigurationChange

    This event is received when the 3D viewer configuration change. It means that you will received this event each time the user change something in the viewer.
    The event to listen to is “onConfigurationChange”. It is accessible using event.data.action.

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

    The received event data parameter will contains the following data

    {
    	currency        : "EUR",     // [string] The currency used to create the configuration,
    	totalPrice      : 0.0,       // [float]  Total price (including tax) of all products in basket,
    	discountContext : "exclTax", // [string] Define the context use to apply the discount (exclTax or inclTax),
    	discount        : 0.0,       // [float]  Global basket discount ,
    	discountType    : "percent", // [string] Discount type (percent or value),
    	reference       : "",        // [string] Basket reference in your information system,
    	code            : "",        // [string] Basket reference on Emersya side,
    	products [                   // [array]  Products list inside the customer basket,
    		{
    			name                     : "",  // [string]  Name of the product,
    			code                     : "",  // [string]  Code of the product,
    			basePrice                : 0.0, // [float    Price without options and without components extra cost,
    			basePriceTax             : 0.2, // [float]   Tax percent,
    			discount                 : 0.0, // [float]   Discount apply to this product,
    			discountType             : "",  // [string]  Type of discount (percent or value),
    			quantity                 : 1,   // [float]   Quantity of product inside the basket,
    			unitPrice                : 0.0, // [integer] Price without discount and without tax => base price + price of each components,
    			amountWithoutTax         : 0.0, // [float]   Amount for this product (tax excluded),
    			amountWithTax            : 0.0, // [float]   Amount for this product (tax included),
    			emersyaConfigurationCode : "",  // [string]  The configuration code (filled when the configuration is saved),
    			thumbURL                 : "",  // [string]  The screenshot of the configuration (filled when the configuration is saved),
    			components               : [],  // [array]   The list of all product components,
    			accessories              : [],  // [array]   The list of all bought accessories,
    			options                  : [],  // [array]   The list of selected options,
    			metaData                 : {}   // [object]  Data stored,
    		}
    	]
    }
    onProceedCheckout

    This event is received when the user validate his backet.
    For each product, we will provide :

    • An emersyaConfigurationCode. You need this code to call the web service, which will retrieve the configuration and check the price on server side
    • A thumbUrl representing the saved configuration. This could be usefull to illustrate the client basket.
    • A file URL for each customTexture. You will need it to create the custom product.
    The event to listen to is “onProceedCheckout”. 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 == "onProceedCheckout"){} }, false);

    The received event data parameter will contains the following data

    {
    	currency        : "EUR",     // [string] The currency used to create the configuration,
    	totalPrice      : 0.0,       // [float]  Total price (including tax) of all products in basket,
    	discountContext : "exclTax", // [string] Define the context use to apply the discount (exclTax or inclTax),
    	discount        : 0.0,       // [float]  Global basket discount ,
    	discountType    : "percent", // [string] Discount type (percent or value),
    	reference       : "",        // [string] Basket reference in your information system,
    	code            : "",        // [string] Basket reference on Emersya side,
    	products [                   // [array]  Products list inside the customer basket,
    		{
    			name                     : "",  // [string]  Name of the product,
    			code                     : "",  // [string]  Code of the product,
    			basePrice                : 0.0, // [float]   Price without options and without components extra cost,
    			basePriceTax             : 0.2, // [float]   Tax percent,
    			discount                 : 0.0, // [float]   Discount apply to this product,
    			discountType             : "",  // [string]  Type of discount (percent or value),
    			unitPrice                : 0.0, // [float]   Price without discount and without tax => base price + price of each components,
    			quantity                 : 1,   // [integer] Quantity of product inside the basket,
    			amountWithoutTax         : 0.0, // [float]   Amount for this product (tax excluded),
    			amountWithTax            : 0.0, // [float]   Amount for this product (tax included),
    			emersyaConfigurationCode : "",  // [string]  This code is generated by emersya,
    			thumbURL                 : "",  // [string]  The screenshot of the configuration,
    			components               : [],  // [array]   The list of all product components,
    			accessories              : [],  // [array]   The list of all bought accessories,
    			options                  : [],  // [array]   The list of selected options,
    			metaData                 : {}   // [object]  Data stored,
    		}
    	]
    }
    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"}, "*");
    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, takeBackground : true, },'*');
    getScreenshots

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

    viewerIframe.postMessage({action : 'getScreenshots', width : 512, height : 512, takeBackground : true, cameras[] },'*');
    proceedCheckout

    This function allows you to complete the configuration, it means that we will save all the products configurations. We will also generate a preview and provide an link URL for each custom texture for each products.

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

    The received event data parameter will contains the following data

    {
    	currency        : "EUR",     // [string] The currency used to create the configuration,
    	totalPrice      : 0.0,       // [float]  Total price (including tax) of all products in basket,
    	discountContext : "exclTax", // [string] Define the context use to apply the discount (exclTax or inclTax),
    	discount        : 0.0,       // [float]  Global basket discount ,
    	discountType    : "percent", // [string] Discount type (percent or value),
    	reference       : "",        // [string] Basket reference in your information system,
    	code            : "",        // [string] Basket reference on Emersya side,
    	products [                   // [array]  Products list inside the customer basket,
    		{
    			name                     : "",  // [string]  Name of the product,
    			code                     : "",  // [string]  Code of the product,
    			basePrice                : 0.2, // [float]   Price without options and without components extra cost,
    			unitPrice                : 0.0, // [float]   Price without discount and without tax => base price + price of each components,
    			basePriceTax             : 0.0. // [float]   Tax percent,
    			discount                 : 0,   // [string]  Discount apply to this product,
    			discountType             : "",  // [float]   Type of discount (percent or value),
    			quantity                 : 1,   // [integer] Quantity of product inside the basket,
    			amountWithoutTax         : 0.0, // [float]   Amount for this product (tax excluded),
    			amountWithTax            : 0.0, // [float]   Amount for this product (tax included),
    			emersyaConfigurationCode : "",  // [string]  This code is generated by emersya,
    			thumbURL                 : "",  // [string]  The screenshot of the configuration,
    			components               : [],  // [array]   The list of all product components,
    			accessories              : [],  // [array]   The list of all bought accessories,
    			options                  : [],  // [array]   The list of selected options,
    			metaData                 : {}   // [object]  Data stored,
    		}
    	]
    }
    getPrice

    This function allows you to retrieve the price of the current configuration and the currency.
    To do it, you have to listen to the "onGetPrice" event

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

    The received event data parameter will contains the following data

    {
    	action : onGetPrice
    	data : {
    		totalPrice : 360   // [float]  Total price (including tax) of all products in basket,
    		currency   : "EUR" // [string] The currency used to create the configuration,
    	}
    }

    A configuration check must be done on server side with the help of our web service (https://emersya.com/ws/0.3/basket/detailsPriceChecked?code=[BASKETCODE]).
    In order to do it we will only required the saved basket code.
    The response will contain the following informations.

    {
    	currency        : "EUR",     // [string] The currency used to create the configuration,
    	totalPrice      : 0.0,       // [float]  Total price (including tax) of all products in basket,
    	discountContext : "exclTax", // [string] Define the context use to apply the discount (exclTax or inclTax),
    	discount        : 0.0,       // [float]  Global basket discount ,
    	discountType    : "percent", // [string] Discount type (percent or value),
    	reference       : "",        // [string] Basket reference in your information system,
    	code            : "",        // [string] Basket reference on Emersya side,
    	products [                   // [array]  Products list inside the customer basket,
    		{
    			name                     : "",  // [string]  Name of the product,
    			code                     : "",  // [string]  Code of the product,
    			basePrice                : 0.0, // [float]   Price without options and without components extra cost,
    			basePriceTax             : 0.2, // [float]   Tax percent,
    			discount                 : 0.0, // [float]   Discount apply to this product,
    			discountType             : "",  // [string]  Type of discount (percent or value),
    			unitPrice                : 0.0, // [float]   Price without discount and without tax => base price + price of each components,
    			quantity                 : 1,   // [integer] Quantity of product inside the basket,
    			amountWithoutTax         : 0.0, // [float]   Amount for this product (tax excluded),
    			amountWithTax            : 0.0, // [float]   Amount for this product (tax included),
    			emersyaConfigurationCode : "",  // [string]  This code is generated by emersya,
    			thumbURL                 : "",  // [string]  The screenshot of the configuration,
    			components               : [],  // [array]   The list of all product components,
    			accessories              : [],  // [array]   The list of all bought accessories,
    			options                  : [],  // [array]   The list of selected options,
    			metaData                 : {}   // [object]  Data stored,
    		}
    	]
    }
    Error Handling

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

    • An api call did not received required parameter
    • An api call received the wrong type of parameter
    • An error occurred while processing the request on server side

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

    The following code is used to generate the content of the example container (container with the pink border).
    Feel free to edit it as you want.
    The buttons inside the example container send event to the apps, you can see the result of the call in the "App response" part.

    Apply

    All the events received by the parent page from the app are displayed in the following part

    App response
    Clear