Documentation de l'API

Certifications
Formations
    Prenez le contrôle total de la vue 3D et
    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.

    Exemple
    Les matières configurables et les variations de matière listées ci-dessous seront utilisées dans tous les exemples dans cette section.
    Matières configurables
    Variations de matière

    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

    Utiliser une iframe

    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

    Avant d'intéragir avec l'app, vous aurez toujours besoin d'initialiser l'API avec l'appel suivant.

    viewerIframe.postMessage({action : "registerCallback"}, "*");
    Utiliser un script

    Une fois que le script 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 l'objet JS représentant la visionneuse Emersya.

    Vous pouvez le récupérer à partir du moment ou vous avez reçu l'événement 'emersyaViewerInitialized'.

    document.addEventListener('emersyaViewerInitialized', function(){
      emersyaViewer = emViewers[ID_DU_CONTENEUR]
    }, false);

    Écouter les évenemments de l'API

    Utiliser une iframe

    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 "){
        // [string] The data is accessible in the event.data object
      }
    }, false);

    Il est possible de désenregistrer la fonction permettant d'écouter les événements de la visionneuse. Pour ce faire, il faudra supprimer l'écouteur sur la "window" courante

    Exemple : Comment désenregistrer la fonction permettant d'écouter les événements remontés par la visionneuse. :

    window.removeEventListener("message", function(event){
       if(event && event.data && event.data.action == " onStateChange "){
        // [string] The data is accessible in the event.data object
      }
    }, false);
    Utiliser un script

    La dernière étape est de recevoir les données envoyées par la visonneuse. Pour ce faire, vous devrez ajouter des écouteurs sur votre objet JS pour chaque événements que vous souhaitez écouter.

    Exemple : Comment récupérer l'état de la visionneuse durant le chargement :

    emersyaViewer.addEventListener("onStateChange", function(data){
        console.log(data);
    });

    Il est possible de désenregistrer les fonctions permettant d'écouter les événements de la visionneuse. Pour ce faire, il faudra supprimer l'écouteur sur votre objet JS.

    Exemple : Comment désenregistrer la fonction permettant d'écouter l'événement "onStateChange":

    emersyaViewer.removeEventListener("onStateChange");

    Vous trouverez la liste complète des événements dans la partie Événement de l'API.

    Quick Start

    Appliquer

    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

    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
    onStateChange

    Cet événement est reçu lorsque la visionneuse 3D change d'état.Il peut s'avérer utile de savoir quand la visionneuse est prète à être utilisée.
    L'événement à écouter est "onStateChange".

    window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onStateChange"){} }, false);

    Le paramètre data de l'événement reçu contiendra les informations suivantes

    {
    	action: "onStateChange"
    	state: {
    		arCompatibility : true,     // [boolean] True si l'AR est disponible sur l'appareil, false sinon,
    		arState         : "",       // [string]  État de l'AR,
    		loadingProgress : 1,        // [float]   Avancement du chargement de la visionneuse,
    		viewerState     : "loaded", // [string]  État de la visionneuse parmi opened | ready | started | loading | loaded| 3dlost | stopped | fallbackloaded,
    		viewerType      : "webgl",  // [string]  Type de visionneuse parmi null| webgl | fallback,
    		webglStatus     : "65536",  // [integer] Status WebGL de la visionneuse,
    		version: {
    			actualProject           : 1,     // [integer] Numéro de version du projet chargé,
    			actualViewer            : 1,     // [integer] Numéro de version de la visionneuse chargée,
    			loadedFromConfiguration : false, // [boolean] Détermine si la visionneuse est chargée à partir d'une configuration existante,
    			routeProject            : 1,     // [integer] Version la plus récente du projet,
    			routeViewer             : 1,     // [integer] Version la plus récente de la visionneuse,
    		}
    	}
    }
    onConfigurationChange

    Cet événement est reçu lorsque la configuration d'un produit change. Cela veut dire que vous recevrez cet évenement à chaque fois que l'utilisateur changera quelque chose dans la visionneuse.
    L'événement à écouter est "onConfigurationChange".

    window.addEventListener("message", function(event){if(event && event.data && event.data.action == "onConfigurationChange"){} }, false);

    Le paramètre data de l'événement reçu contiendra les informations suivantes

    {
    	currency        : "EUR",     // [string] La devise utilisée pour créer la configuration,
    	totalPrice      : 0.0,       // [float]  Prix total (taxe incluse) de l'ensemble des produits présents dans le panier,
    	discountContext : "exclTax", // [string] Détermine le contexte dans lequel est appliquée la réduction (exclTax ou inclTax),
    	discount        : 0.0,       // [float]  Réduction sur le panier,
    	discountType    : "percent", // [string] Type de réduction (pourcentage ou valeur),
    	reference       : "",        // [string] Référence du panier dans votre système d'information,
    	code            : "",        // [string] Référence du panier du coté d'Emersya,
    	products [                   // [array]  Liste des produits couramment dans le panier de l'utilisateur,
    		{
    			name                     : "",  // [string]  Nom du produit,
    			code                     : "",  // [string]  Code du produit,
    			basePrice                : 0.0, // [float    Prix sans options payantes et sans surcoût lié aux composants,
    			basePriceTax             : 0.2, // [float]   Pourcentage de taxe,
    			discount                 : 0.0, // [float]   Réduction appliqué à ce produit,
    			discountType             : "",  // [string]  Type de réduction (percent or value),
    			quantity                 : 1,   // [float]   Quantité de produit dans le panier,
    			unitPrice                : 0.0, // [integer] Prix sans remise et sans taxe => Prix de base + prix de chaque composant,
    			amountWithoutTax         : 0.0, // [float]   Montant pour ce produit (taxe non incluse),
    			amountWithTax            : 0.0, // [float]   Montant pour ce produit (taxe incluse),
    			emersyaConfigurationCode : "",  // [string]  Le code de configuration (remplit au moment de la sauvegarde de la configuration),
    			thumbURL                 : "",  // [string]  Le screenshot de la configuration (remplit au moment de la sauvegarde),
    			components               : [],  // [array]   La liste des composants du produit,
    			accessories              : [],  // [array]   La liste de tous les accessoires achetés,
    			options                  : [],  // [array]   La liste des options sélectionnées,
    			metaData                 : {}   // [object]  Données stockées,
    		}
    	]
    }
    onProceedCheckout

    Cet événement est reçu lorsque l'utilisateur valide son panier. Pour chaque produit, nous fournirons :

    • Un emersyaConfigurationCode. Vous aurez besoin de ce code pour appeller le web service qui permet de retrouver la configuration et vérifier le prix coté serveur
    • Un thumburl représentant la configuration sauvegardée. Cela peut être utile afin d'illustrer le panier de votre client
    • Un lien URL pour chaque customTexture. Vous aurez besoin de ces images afin de créer le produit commandé

    L'événement à écouter est "onProceedCheckout".
    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 == "onProceedCheckout"){} }, false);

    Le paramètre data de l'événement reçu contiendra les informations suivantes

    {
    	currency        : "EUR",     // [string] La devise utilisée pour créer la configuration,
    	totalPrice      : 0.0,       // [float]  Prix total (taxe incluse) de l'ensemble des produits présents dans le panier,
    	discountContext : "exclTax", // [string] Détermine le contexte dans lequel est appliquée la réduction (exclTax ou inclTax),
    	discount        : 0.0,       // [float]  Réduction sur le panier,
    	discountType    : "percent", // [string] Type de réduction (pourcentage ou valeur),
    	reference       : "",        // [string] Référence du panier dans votre système d'information,
    	code            : "",        // [string] Référence du panier du coté d'Emersya,
    	products [                   // [array]  Liste des produits couramment dans le panier de l'utilisateur,
    		{
    			name                     : "",  // [string]  Nom du produit,
    			code                     : "",  // [string]  Code du produit,
    			basePrice                : 0.0, // [float]   Prix sans options payantes et sans surcoût lié aux composants,
    			basePriceTax             : 0.2, // [float]   Pourcentage de taxe,
    			discount                 : 0.0, // [float]   Réduction appliqué à ce produit,
    			discountType             : "",  // [string]  Type de réduction (percent or value),
    			unitPrice                : 0.0, // [float]   Prix sans remise et sans taxe => Prix de base + prix de chaque composant,
    			quantity                 : 1,   // [integer] Quantité de produit dans le panier,
    			amountWithoutTax         : 0.0, // [float]   Montant pour ce produit (taxe non incluse),
    			amountWithTax            : 0.0, // [float]   Montant pour ce produit (taxe incluse),
    			emersyaConfigurationCode : "",  // [string]  Ce code est généré par emersya,
    			thumbURL                 : "",  // [string]  Le screenshot de la configuration,
    			components               : [],  // [array]   La liste des composants du produit,
    			accessories              : [],  // [array]   La liste de tous les accessoires achetés,
    			options                  : [],  // [array]   La liste des options sélectionnées,
    			metaData                 : {}   // [object]  Données stockées,
    		}
    	]
    }
    Fonctions disponible à travers l'API
    getViewerState

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

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

    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[] },'*');
    proceedCheckout

    Cette fonction achève la configuration, cela signifie que tous les produits du panier seront sauvegardés. Nous fournirons également un rendu de la configuration ainsi qu'un lien vers l'image sauvegardée pour chaque custom texture de chaque produit.

    viewerIframe.postMessage({action:"proceedCheckout"}, "*");

    Le paramètre data de l'événement reçu contiendra les informations suivantes

    {
    	currency        : "EUR",     // [string] La devise utilisée pour créer la configuration,
    	totalPrice      : 0.0,       // [float]  Prix total (taxe incluse) de l'ensemble des produits présents dans le panier,
    	discountContext : "exclTax", // [string] Détermine le contexte dans lequel est appliquée la réduction (exclTax ou inclTax),
    	discount        : 0.0,       // [float]  Réduction sur le panier,
    	discountType    : "percent", // [string] Type de réduction (pourcentage ou valeur),
    	reference       : "",        // [string] Référence du panier dans votre système d'information,
    	code            : "",        // [string] Référence du panier du coté d'Emersya,
    	products [                   // [array]  Liste des produits couramment dans le panier de l'utilisateur,
    		{
    			name                     : "",  // [string]  Nom du produit,
    			code                     : "",  // [string]  Code du produit,
    			basePrice                : 0.2, // [float]   Prix sans options payantes et sans surcoût lié aux composants,
    			unitPrice                : 0.0, // [float]   Prix sans remise et sans taxe => Prix de base + prix de chaque composant,
    			basePriceTax             : 0.0. // [float]   Pourcentage de taxe,
    			discount                 : 0,   // [string]  Réduction appliqué à ce produit,
    			discountType             : "",  // [float]   Type de réduction (percent or value),
    			quantity                 : 1,   // [integer] Quantité de produit dans le panier,
    			amountWithoutTax         : 0.0, // [float]   Montant pour ce produit (taxe non incluse),
    			amountWithTax            : 0.0, // [float]   Montant pour ce produit (taxe incluse),
    			emersyaConfigurationCode : "",  // [string]  Ce code est généré par emersya,
    			thumbURL                 : "",  // [string]  Le screenshot de la configuration,
    			components               : [],  // [array]   La liste des composants du produit,
    			accessories              : [],  // [array]   La liste de tous les accessoires achetés,
    			options                  : [],  // [array]   La liste des options sélectionnées,
    			metaData                 : {}   // [object]  Données stockées,
    		}
    	]
    }
    getPrice

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

    Une vérification coté serveur doit être faite à l'aide de notre web service (https://emersya.com/ws/0.3/basket/detailsPriceChecked?code=[BASKETCODE]).
    Pour ce faire, nous avons seulement besoin du code du panier sauvegardé.
    La réponse contiendras les informations suivantes.

    {
    	currency        : "EUR",     // [string] La devise utilisée pour créer la configuration,
    	totalPrice      : 0.0,       // [float]  Prix total (taxe incluse) de l'ensemble des produits présents dans le panier,
    	discountContext : "exclTax", // [string] Détermine le contexte dans lequel est appliquée la réduction (exclTax ou inclTax),
    	discount        : 0.0,       // [float]  Réduction sur le panier,
    	discountType    : "percent", // [string] Type de réduction (pourcentage ou valeur),
    	reference       : "",        // [string] Référence du panier dans votre système d'information,
    	code            : "",        // [string] Référence du panier du coté d'Emersya,
    	products [                   // [array]  Liste des produits couramment dans le panier de l'utilisateur,
    		{
    			name                     : "",  // [string]  Nom du produit,
    			code                     : "",  // [string]  Code du produit,
    			basePrice                : 0.0, // [float]   Prix sans options payantes et sans surcoût lié aux composants,
    			basePriceTax             : 0.2, // [float]   Pourcentage de taxe,
    			discount                 : 0.0, // [float]   Réduction appliqué à ce produit,
    			discountType             : "",  // [string]  Type de réduction (percent or value),
    			unitPrice                : 0.0, // [float]   Prix sans remise et sans taxe => Prix de base + prix de chaque composant,
    			quantity                 : 1,   // [integer] Quantité de produit dans le panier,
    			amountWithoutTax         : 0.0, // [float]   Montant pour ce produit (taxe non incluse),
    			amountWithTax            : 0.0, // [float]   Montant pour ce produit (taxe incluse),
    			emersyaConfigurationCode : "",  // [string]  Ce code est généré par emersya,
    			thumbURL                 : "",  // [string]  Le screenshot de la configuration,
    			components               : [],  // [array]   La liste des composants du produit,
    			accessories              : [],  // [array]   La liste de tous les accessoires achetés,
    			options                  : [],  // [array]   La liste des options sélectionnées,
    			metaData                 : {}   // [object]  Données stockées,
    		}
    	]
    }
    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 paramètre est manquant
    • Un paramètre reçu n'est pas du bon type
    • Une erreur sur notre serveur est survenue 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"

    Appliquer

    Tous les événements reçus par la page parent depuis l'application Emersya seront affichés dans la partie ci-dessous

    Réponse de l'application
    Vider