créez les expériences produit et configurateurs les plus poussés
L'API complète d'Emersya vous permet de créer facilement et de manière transparente vos propres interfaces.
Vous pourrez effectuer des changements parmi les options disponibles, passer d'un point de vue à un autre, détecter les interactions provenant de la vue 3D, et bien plus encore.
L'API Emersya fournit tout ce dont vous avez besoin pour créer les expériences d'achat les plus évoluées et cela sans compétences avancées en développement. De simples connaissances basiques en HTML et Javascript suffisent.
Bonnes pratiques
Grouper les appels à l'API
Toujours essayer de créer votre code afin de grouper les appels à l'API.
Par exemple de ne pas oublier de :
- Grouper les configurations dans le même appel à 'setMaterialsGroupConfigurations.'
- Grouper tous les appels à 'setMaterialByName' dans la même transaction ou d'utiliser 'setMaterialsByName'.
Dans le cas où vous ne pouvez pas les regrouper, il est très important de toujours attendre l'événement "onSuccess" avant de faire un nouvel appel à l'API.
Éviter d'appeler des fonctions de configuration de l'API simultanément
Ne pas appeler de nouvelle fonction de configuration avant d'avoir reçu l'événement "onSuccess" de la précédente.
Par exemple :
- Ne pas appeler une transaction en même temps qu'un "setMaterialsGroupConfiguration".
- Ne pas appeler de "setMaterialsGroupConfiguration" en même temps qu'un "applyPreset".
- Ne pas appeler "applyPreset" en même temps qu'une transaction.
Mettre à jour des éléments configurables
Les fonctions updateCustomTexture et updateCustomText replacent les textures de manière instantanée. Il est possible de voir la texture disparaître durant le chargement de la nouvelle.
La meilleure solution dans ce cas, est de faire la mise à jour pendant que la texture n'est pas visible et de la faire apparaître après le chargement.
Appel des fonctions de l'API
Fonctions de l'API et niveaux de fonctionnalités de la visionneuse 3D
Pour chaque fonction de l'API, le niveau de fonctionnalités de la visionneuse 3D requis sera indiqué : Visualiser, Animer ou Configurer.
Pour que la fonction de l'API fonctionne, la visionneuse 3D doit avoir le niveau de fonctionnalité correspondant activé.
Le niveau de fonctionnalité de la visionneuse 3D peut être défini sur la plateforme Emersya, dans le menu Visionneuses 3D intégrables du projet.
Écouter les événements de l'API
Vous trouverez la liste complète des événements dans la partie Événement de l'API.
Démarrage rapide
API app clé en main
Une fois que l'iframe de l'app a été embarqué dans votre page, il est possible d'appeler les fonctions de l'API afin d'échanger des informations.
Pour faire cela, il faut dans un premier temps récupérer le DOM de l'élément contenant l'iframe.
viewerIframe = document.getElementById("emersyaIframe").contentWindow;Vous devrez ensuite appeler l'API avec la fonction postMessage.
Avant d'intéragir avec l'app, vous aurez toujours besoin d'initialiser l'API avec l'appel suivant.
viewerIframe.postMessage({action : "initializeAPI"}, "*");L'étape final est de recevoir les données et les événements envoyés par la visionneuse. Pour ce faire, il vous faudra ajouter un écouteur d'événement à la fenêtre du site parent embarquant l'iframe.
L'exemple suivant permet de récupérer le statut de la visionneuse.
window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onStateChange"){} }, false); Événement automatiquement envoyé par l'application
Cet événement est reçu lorsque l'utilisateur valide son panier.
Nous fournirons uniquement le code de configuration du panier.
Pour retrouver l'ensemble des données du panier, il faudra interroger notre web service.
L'événement à écouter est "onProceedCheckout".
Dans ce cas event.data contiendra le code du panier.
window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onProceedCheckout"){} }, false);
Le paramètre data paramètre de l'événement reçu contiendra les informations suivantes
{
action : "onProceedCheckout",
basket : {
code : "" // [string] Référence du panier du coté d'Emersya,
}
}Fonctions disponibles à travers l'API
Afin de récupérer l'état de la visionneuse, il vous faudra écouter l'événement "onStateChange".
Il est possible que le site qui embarque l'application rate des événements en fonction de la vitesse à laquelle ce dernier charge par rapport à la visionneuse Emersya.
Il est possible pour le site parent de recevoir plusieurs événements de type "loading". Ces événements indiquent la progression du chargement.
viewerIframe.postMessage({action:"getViewerState"}, "*");
Cette fontion permet de faire un screenshot, l'appel est le même que celui de l'API (https://emersya.com/en/api/getScreenshot)
L'événement de retour est "onSceenshot"
viewerIframe.postMessage({action : 'getScreenshot', width : 512, height : 512, takeBackground : true, },'*');
Cette fontion permet de faire des screenshots, l'appel est le même que celui de l'API (https://emersya.com/en/api/getScreenshots)
L'événement de retour est "onSceenshots"
viewerIframe.postMessage({action : 'getScreenshots', width : 512, height : 512, takeBackground : true, cameras[] },'*');
Cette fonction vous permet d'achever la configuration, cela signifie que toutes les configurations produit seront sauvegardés.
L'événement à écouter est "onProceedCheckout".
viewerIframe.postMessage({action:"proceedCheckout"}, "*");
Cette fonction permet de récupérer le prix de la configuration actuelle de la visionneuse, ainsi que la devise d'achat.
Pour ce faire, il vous faudra écouter l'événement de retour "onGetPrice".
viewerIframe.postMessage({action:"getPrice"}, "*");
Le paramètre data paramètre de l'événement reçu contiendra les informations suivantes
{
action : onGetPrice
data : {
totalPrice : 360 // [float] Prix total (taxe incluse) de l'ensemble des produits présents dans le panier,
currency : "EUR" // [string] La devise utilisée pour créer la configuration,
}
}Il est dangereux de se fier à une information retournée coté client, c'est pourquoi, une vérification coté serveur doit être faite à l'aide de notre web service (https://emersya.com/ws/0.3/basket/get/[BASKETCODE]).
Fonctions disponibles à travers notre Web Service
Cette fonction permet de récupérer les informations nécessaires afin de compléter la commande (prix, miniatures, détails)
Pour ce faire, vous devez simplement interroger notre web service avec le code référençant le panier.
Ce code vous a été retourné avec l'événement onProceedCheckout. Vous devez être loggé pour utiliser cette fonction du web service. https://emersya.com/ws/0.3/basket/get/BASKETCODE
La réponse du web service contiendra les informations suivantes
{
reference : { // [object] Détails de la référence du panier,
value : "", // [string] Valeur de la référence,
barcode : {
type : "", // [string] Type de code barre,
URL : "" // [string] URL du code barre,
}
},
code : "", // [string] Référence du panier du coté d'Emersya,
locale : "fr-fr", // [string] Langue de l'application au moment de l'enregistrement du panier,
currency : "EUR", // [string] La devise utilisée pour créer la configuration,
discountContext : "exclTax", // [string] Détermine le contexte dans lequel est appliquée la réduction (exclTax ou inclTax),
taxesContext : [], // [array] Context des taxes,
totalPrice : {
exclTax : 0.0, // [float] Prix total sans taxes,
inclTax : 0.0 // [float] Prix total avec les taxes,
},
discount : {
value : 0.0, // [float] Réduction sur le panier,
type : "" // [string] Type de réduction (pourcentage ou valeur),
},
state : "unpaid", // [string] Etat de la commande (non payée, sauvegardée, payée, annulée),
billingAddress : {}, // [object] Détails de l'adresse de facturation,
deliveryAddress : {}, // [object] Détails de l'adresse de livraison,
metaData : {}, // [object] Metadonnées,
pdfRecapURL : "", // [string] URL du PDF,
products : [ // [array] Liste des produits couramment dans le panier de l'utilisateur,
{
name : "", // [string] Nom du produit,
title : "", // [string] Nom du produit traduit,
reference : { // [object] Détails du code du produit,
value : "", // [string] Valeur du code,
barcode : {
type : "", // [string] Type de code barre,
URL : "" // [string] URL du code barre,
}
},
sku : { // [object] Détails du SKU du produit,
value : "", // [string] Valeur du SKU,
barcode : {
type : "", // [string] Type de code barre,
URL : "" // [string] URL du code barre,
}
},
gtin : { // [object] Détails du GTIN du produit,
value : "" // [string] Valeur du GTIN,
barcode : {
type : "", // [string] Type de code barre,
URL : "" // [string] URL du code barre,
}
},
basePrice : {
exclTax : 0.0, // [float] Prix de base sans les taxes,
inclTax : 0.0 // [float] Prix de base avec les taxes,
},
unitPrice : {
exclTax : 0.0, // [float] Prix unitaire sans taxes,
inclTax : 0.0 // [float] Prix unitaire avec taxes,
},
quantity : 1, // [integer] Quantité de produit dans le panier,
discount : {
value : 0.0, // [float] Valeur de la remise appliquée pour ce produit,
type : "" // [string] Type de remise appliquée pour ce produit,
},
price : {
exclTax : 0.0, // [float] Prix du produit sans les taxes,
inclTax : 0.0 // [float] Prix du produit avec les taxes,
},
savedConfigurationCode : "", // [string] Le code de configuration (remplit au moment de la sauvegarde de la configuration),
thumbnailURL : "", // [string] Le screenshot de la configuration (remplit au moment de la sauvegarde),
images : [{ // [array] Tableau d'images ou de screenshots du produit (généré coté serveur),
reference : "", // [string] Référence de l'image,
URL : "", // [string] URL de l'image,
thumbnailURL : "" // [string] URL de l'image miniature,
}],
savedConfigurationReplayURL : "", // [string] URL pour visualiser le produit configuré,
configuratorReplayURL : "", // [string] URL pour recharger l'app avec le produit configué,
metaData : {}, // [object] Données stockées,
pdfRecapURL : "", // [string] Lien vers le PDF résumant la configuration,
parts : [ // [array] Définition de toutes les parties composant le produit,
{
name : "", // [string] Nom de la partie,
title : "", // [string] Nom traduit de la partie,
reference : { // [object] Détails du code de la partie,
value : "", // [string] Valeur du code,
barcode : {
type : "", // [string] Type de code barre,
URL : "" // [string] URL du code barre,
}
},
price : {
exclTax : 0.0, // [float],
inclTax : 0.0 // [float],
},
taxes : [], // [array] Taxe s'appliquant à cette partie,
discount : {
value : 0.0, // [float] Réduction s'appliquant à cette partie,
type : "" // [string] Type de réduction appliqué,
},
metaData : {}, // [object] Meta données,
parts : [], // [array] Sous partie de l'élément,
option : { // [object] Détails de l'option sélectionné,
name : "", // [string] Nom,
reference : { // [object] Code,
value : "", // [string] Valeur du code,
barcode : {
type : "", // [string] Type de code barre,
URL : "" // [string] URL du code barre,
}
}
price : {
exclTax : 0.0, // [float],
inclTax : 0.0 // [float],
},
taxes : [], // [array] Taxes,
discount : {
value : 0.0, // [float] Valeur de la réduction,
type : "" // [string] Type de réduction,
},
metaData : {}, // [object] Metadonnées,
components : [{ // [array] Liste de composant,
reference : { // [object] Code,
value : "", // [string] Valeur,
barcode : {
type : "", // [string] Type de code barre,
URL : "" // [string] URL du code barre,
}
},
sku : { // [object] SKU,
value : "", // [string] Valeur,
barcode : {
type : "", // [string] Type de code barre,
URL : "" // [string] URL du code barre,
}
},
gtin : { // [object] GTIN,
value : "" // [string] Valeur,
barcode : {
type : "", // [string] Type de code barre,
URL : "" // [string] URL du code barre,
}
},
name : "", // [string] Nom,
imageURL : "", // [string] URL de l'image,
}],
customColor : {}, // [object] Couleur personnalisée,
customTexts : { // [object] textes personnalisés,
"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] Images personnalisées,
customPatterns : [], // [array] Modèles personnalisés ,
},
}
]
}
]
}Gestion des erreurs
Il est nécessaire d'écouter les messages d'erreurs envoyés par l'iframe afin de récupérer les informations sur les éventuels problèmes rencontrés par la visionneuse 3D.
L'événement reçu dans ce cas est "onError".
Une erreur est envoyée lorsque :
- Un appel de l'API n'a pas reçu les paramètres requis
- Un appel de l'APi a reçu de mauvais paramètres
- Une erreur est survenue sur nos serveur durant le traitement de la requête
window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onError"){} }, false);
Exemple
Le code qui suit permet de générer le contenue de l'exemple (conteneurs avec la bordure rose).
Vous pouvez éditer cette partie comme vous le souhaitez.
les boutons dans l'exemple envoient des messages à l'application, vous pouvez voir le résultat de ces appels dans la partie "Réponse de l'application"
Tous les événements reçus par la page parent depuis l'application Emersya seront affichés dans la partie ci-dessous