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 fournie tout ce dont vous avez besoin pour créer les experiences 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'appeller des fonctions de configuration de l'API simultanément
Ne pas appeller de nouvelle fonction de configuration avant d'avoir reçu l'événement "onSuccess" de la précédente
Par exemple :
- Ne pas appeller une transaction en même temps qu'un "setMaterialsGroupConfiguration".
- Ne pas appeller de "setMaterialsGroupConfiguration" en même temps qu'un "applyPreset".
- Ne pas appeller "applyPreset" en même temps qu'une transaction.
- Ne pas appeller une transaction en même temps qu'un "setMaterialsGroupConfiguration".
- Ne pas appeller de "setMaterialsGroupConfiguration" en même temps qu'un "applyPreset".
- Ne pas appeller "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.
Appeller les fonctions de l'API
Une fois que l'iframe a été embarqué dans votre page, il est possible d'appeller les fonctions de l'API afin de prendre le contrôle sur la 3D.
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 appeller l'API avec la fonction postMessage
Pour tous les appels à l'API, il est nécessaire d'avoir au préalable appeller la fonction registerCallback
viewerIframe.postMessage({action : "registerCallback"}, "*");
Écouter les évenemments de l'API
La dernière étape est de recevoir les données envoyées par la visonneuse. Dans ce but, vous devrez premièrement ajouter un event listener sur votre "window" courante.
Exemple : Comment récupérer l'état de la visionneuse durant le chargement :
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
API app clé en main
Une fois que l'iframe de l'app a été embarqué dans votre page, il est possible d'appeller 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 appeller l'API avec la fonction postMessage
Pour tous les appels à l'API, il est nécessaire d'avoir au préalable appeller la fonction registerCallback
viewerIframe.postMessage({action : "registerCallback"}, "*");
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.
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 la visionneuse 3D change d'état.
L'événement a écouter est "onStateChange".
window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onStateChange"){} }, false);
Cet événement est reçu lorsque la configuration d'un produit change.
L'événement à écouter est "onConfigurationChange".
Dans ce cas event.data contiendra la configuration courante de l'objet configuré.
window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onConfigurationChange"){} }, false);
Cet événement est reçu lorsque l'utilisateur clique sur le bouton "Acheter" ou autre de l'application.
L'événement à écouter est "onConfigurationComplete".
Dans ce cas event.data contiendra la configuration courante de l'objet configuré.
window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onConfigurationComplete"){} }, false);
Fonctions disponible à 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 fonction permet de définir la configuration du produit.
L'object de configuration à transmettre sera du même type d'objet que celui reçu par l'événement "onConfigurationComplete".
viewerIframe.postMessage({action:"setConfiguration", configuration : CONFIGURATION }, "*");
Cette fonction permet de récupérer la configuration actuelle de la visionneuse.
Pour ce faire, il vous faudra écouter l'événement de retour "onConfigurationComplete".
viewerIframe.postMessage({action:"getConfiguration"}, "*");
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 },'*');
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".
window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onError"){} }, false);
Tous les examples seront illustrés à partir du modèle 3D suivant :
- logo
- cube
-
brushed_metal -
white_plastic
-
black_plastic_mat -
beige_leather -
glossy_gold
-
black_plastic
-
glossy_bamboo -
teal_plastic