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
    onProceedCheckout

    Cet événement est reçu lorsque l'utilisateur valide son panier.
    Nous fournirons uniquement le code du panier.
    Pour retrouver l'ensemble des données du panier, il faudra intérroger 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 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 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.
    L'événement à écouter est "onProceedCheckout".

    viewerIframe.postMessage({action:"proceedCheckout"}, "*");
    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,
    	}
    }

    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 disponible à travers notre Web Service
    basket/get/BASKETCODE

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

    La plateforme Emersya permet aux marques de créer, intégrer et partager efficacement des expériences et configurateurs produit en 3D interactive haute qualité, pour le e-commerce et le retail.

    Fonctionnalités
    Langue
    Anglais Francais
    Merci! Vous serez averti en premier des dernières mises à jour
    En utilisant Emersya, vous acceptez les
    Conditions d'utilisations