Javascript API documentation

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"}, "*");

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

Events automatically sent by the app

onProceedCheckout

This event is received when the user validate his backet.
We will only provide the basket configuration code.
To retrieve all the basket data you will have to call our web service

The event to listen to is “onProceedCheckout”. It is accessible using event.data.action.
Here, event.data will contain the basket code.

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

The received event data parameter will contains the following data

{
	action : "onProceedCheckout",
	basket : {
		code : "" // [string] Basket reference on Emersya side,
	}
}

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.
The event to listen to is "onProceedCheckout".

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

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

You can not trust data returned on client side, that's why a configuration check must be done on server side with the help of our web service (https://emersya.com/ws/0.3/basket/get/[BASKETCODE]).

Features available through the Web Service

basket/get/BASKETCODE

This function allows you to retrieve all the required information to complete an order (price, thumbnail, details)
In order to do it, simply call our web service with the code referencing the basket.
This code have been received with the onProceedCheckout event.
You need to be logged in to use this web service function

https://emersya.com/ws/0.3/basket/get/BASKETCODE

The response will contain the following data.

{
	reference       : {          // [object]  Reference details of the basket,
	   value : "",               // [string]  Reference value,
	   barcode : {
	       type : "",            // [string]  Barcode type,
	       URL  : ""             // [string]  Barcode URL,
	   }
	},
	code            : "",        // [string] Basket reference on Emersya side,
	locale          : "fr-fr",   // [string] App language when saving basket,
	currency        : "EUR",     // [string] The currency used to create the configuration,
	discountContext : "exclTax", // [string] Define the context use to apply the discount (exclTax or inclTax),
	taxesContext    : [],        // [array]  Taxes context,
	totalPrice      : {
	    exclTax : 0.0,           // [float] Total price without taxes,
	    inclTax : 0.0            // [float] Total price with taxes,
	},
	discount  : {
	    value : 0.0,             // [float]  Global basket discount,
	    type  : ""               // [string] Discount type (percent or value),
	},
	state : "unpaid",            // [string] State of the basket ( unpaid | saved | paid | canceled ),
	billingAddress  : {},        // [object] Billing address details,
	deliveryAddress  : {},       // [object] Delivery address details,
	metaData  : {},              // [object] Metadata informations,
	pdfRecapURL : "",            // [string] PDF URL,
	products : [                 // [array]  Products list inside the customer basket,
	   {
	       name      : "",       // [string]  Name of the product,
	       title     : "",       // [string]  Translated product name,
	       reference : {         // [object]  Code details of the product,
	        value    : "",       // [string]  Code value,
	        barcode  : {
	            type : "",       // [string]  Barcode type,
	            URL  : ""        // [string]  barcode URL,
	        }
	       },
	       sku : {               // [object]  SKU details of the product,
	           value : "",       // [string]  SKU value,
	           barcode : {
	               type : "",    // [string]  Barcode type,
	               URL  : ""     // [string]  Barcode URL,
	           }
	       },
	       gtin : {              // [object]  GTIN details of the product,
	       	   value    : ""     // [string]  GTIN value,
	       	   barcode  : {
	       	       type : "",    // [string]  Barcode type,
	       	       URL  : ""     // [string]  Barcode URL,
	       	   }
	       },
	       basePrice    : {
	       	exclTax : 0.0,       // [float] Base price without taxes,
	       	inclTax : 0.0        // [float] Base price with taxes,
	       },
	       unitPrice    : {
	       	exclTax : 0.0,       // [float] Unit price without taxes,
	       	inclTax : 0.0        // [float] Unit price with taxes,
	       },
	       quantity  : 1,        // [integer]   Quantity of product inside the basket,
	       discount  : {
	       	value : 0.0,         // [float]  Discout value apply for the product,
	       	type  : ""           // [string] Discount type applied for the product,
	       },
	       price       : {
	       	exclTax : 0.0,       // [float] Product price without taxes,
	       	inclTax : 0.0        // [float] Product price with taxes,
	       },
	       savedConfigurationCode      : "",  // [string] The configuration code (filled when the configuration is saved),
	       thumbnailURL                : "",  // [string] The screenshot of the configuration (filled when the configuration is saved),
	       images                      : [{   // [array]  Array of screenshots or images of the product (generated server side),
	          reference                : "",  // [string] Image reference,
	          URL                      : "",  // [string] Image URL,
	          thumbnailURL             : ""   // [string] Image thumbnail URL,
	       }],
	       savedConfigurationReplayURL : "",  // [string] URL to visualize the configurated product,
	       configuratorReplayURL       : "",  // [string] URL to load the app with the configurated product,
	       metaData                    : {},  // [object] Data stored,
	       pdfRecapURL                 : "",  // [string] Link to the PDF configuration sum up,
	       parts                       : [    // [array]  Definition of all parts composing the product,
	           {
	                name      : "",       // [string]  Part name,
	                title     : "",       // [string]  Translated part name,
	                reference : {         // [object]  Code details of the part,
	                 value    : "",       // [string]  Code value,
	                 barcode  : {
	                     type : "",       // [string]  Barcode type,
	                     URL  : ""        // [string]  Barcode url,
	                 }
	                },
	                price       : {
	                    exclTax : 0.0,           // [float],
	                    inclTax : 0.0            // [float],
	                },
	                taxes           : [],        // [array]  Taxes applied to this part,
	                discount  : {
	                    value : 0.0,             // [float]  Discount applied to this part,
	                    type  : ""               // [string] Discount type applied,
	                },
	                metaData  : {},              // [object] Metadata informations,
	                parts     : [],              // [array]  Subparts of the part,
	                option    : {                // [object] Option détails,
	                    name      : "",          // [string]  Name,
	                    reference : {            // [object]  Code,
	                    value     : "",          // [string]  Code value,
	                    barcode   : {
	                        type  : "",          // [string]  Barcode type,
	                        URL   : ""           // [string]  Barcode URL,
	                      }
	                    }
	                    price       : {
	                        exclTax : 0.0,           // [float],
	                        inclTax : 0.0            // [float],
	                    },
	                    taxes           : [],    // [array]  Taxes applied,
	                    discount  : {
	                 	    value : 0.0,         // [float]  discount value,
	                 	    type  : ""           // [string] Discount type,
	                    },
	                    metaData   : {},         // [object] Metadata,
	                    components : [{          // [array]  Components list,
	                        reference   : {         // [object] Code,
	                           value    : "",    // [string] Value,
	                           barcode  : {
	                               type : "",    // [string] Barcode type,
	                               URL  : ""     // [string] Barcode URL,
	                           }
	                        },
	                        sku : {              // [object] SKU,
	                            value : "",      // [string] Value,
	                            barcode : {
	                                type : "",   // [string] barcode type,
	                                URL  : ""    // [string] barcode URL,
	                            }
	                        },
	                        gtin : {             // [object] GTIN,
	       	                    value    : ""    // [string] Value,
	       	                    barcode  : {
	       	                        type : "",   // [string] Barcode type,
	       	                        URL  : ""    // [string] barcode URL,
	       	                    }
	                        },
	                        name           : "", // [string] Name,
	                        imageURL       : "", // [string] Image URL,
	                    }],
	                    customColor    : {}, // [object] Custom color,
	                    customTexts    : {   // [object] Custom texts,
	                        "productionParameters" : "", // [string]
	                        "verticalAlignment"    : "", // [string]
	                        "horizontalAlignment"  : "", // [string]
	                        "texts":[{
	                                "configurableMaterial": "",    // [string]
	                                "materialVariation"   : "",    // [string]
	                                "text"                : "",    // [string]
	                                "font"                : "",    // [string]
	                                "size"                : 0.0,   // [float]
	                                "color"               : "",    // [string]
	                                "colorType"           : "",    // [string]
	                                "productionFileURL"   : "",    // [string]
	                                "productionFileType"  : "",    // [string]
	                                "italic"              : false, // [bool]
	                                "bold"                : false, // [bool]
	                                "underline"           : false, // [bool]
	                                "strokeText"          : false, // [bool]
	                                "strokeColor"         : "",    // [string]
	                                "strokeColorType"     : "",    // [string]
	                                "offsetPosition"      : [0,0], // [array]
	                                "rotation"            : 0,     // [integer]
	                                "scaling"             : [1,1], // [array]
	                                "verticalAlignment"   : "",    // [string]
	                                "horizontalAlignment" : "",    // [string]
	                                "productionTechnique" : "",    // [string]
	                                "price"               : {
	                                    exclTax : 0.0,             // [float],
	                                    inclTax : 0.0              // [float],
	                                },
	                                "discount"            : {
	                                    "value" :0.0,              // [float]
	                                    "type"  :""                // [string]
	                                },
	                                "metaData"            : {},    // [object]
	                            }]
	                    },
	                    customImages   : [], // [array]  Custom images,
	                    customPatterns : [], // [array]  Custom patterns,
	                },
	           }
	       ]
	   }
	]
}

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