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

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

    API functions and 3D viewer feature levels

    For each API function, the required 3D viewer feature level will be indicated: Visualize, Play or Customize.

    For the API function to work, the 3D viewer must have the corresponding feature level enabled.
    The 3D viewer feature level can be defined on the Emersya Platform, on the Embeddable 3D viewers menu for the project to be embedded.

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

    The Emersya online platform empowers brands and retailers to streamline their product design, marketing & production workflows, from product conception to eCommerce and mass customization, using advanced Interactive 3D & AR technology.

    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