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
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
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
You will find the complete listenable event in the API events section
Quick Start
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
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
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"}, "*");
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, },'*');
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[] },'*');
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"}, "*");
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
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.
All the events received by the parent page from the app are displayed in the following part