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 comming 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 knoledge of HTML and javascript.

Example used in this documentation

The editable parts and available materials listed below will be used through all the examples in this API section.

Editable parts

Available materials

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

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

Listening to API events

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);

Quick Start

Apply

All examples will be illustarted with the following 3D model :

The editable parts are :

logo
cube

The logo and the cube materials could be set to the following settings :

brushed_metal
white_plastic
black_plastic_mat
beige_leather
glossy_gold
black_plastic
glossy_bamboo
teal_plastic