Documentation Javascript de l'API

Certifications
Demander une formation
    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 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.

    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'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

    Utiliser une iframe

    Une fois que l'iframe a été embarquée dans votre page, il est possible d'appeler les fonctions de l'API directement depuis cette page afin de prendre le contrôle sur la 3D et é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 : "registerCallback"}, "*");
    Utiliser un script

    Une fois que le script a été embarqué dans votre page, il est possible d'appeler les fonctions de l'API directement depuis cette page afin de prendre le contrôle sur la 3D et échanger des informations.

    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 où vous avez reçu l'événement 'emersyaViewerInitialized'.

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

    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

    Utiliser une iframe

    La dernière étape est de recevoir les données et réponses envoyées par l'iframe. Dans ce but, vous devrez premièrement ajouter un event listener dans les éléments de la fenêtre du site parent sur lequel l'iframe est embarquée. L'exemple suivant vous montre comment retrouver le status de la visionneuse 3D.

    Exemple : Comment récupérer l'état de la visionneuse durant son 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 et réponse envoyées par l'iframe. Pour ce faire, vous devrez ajouter des "events listeners" à votre objet JS pour chaque événement que vous souhaitez gérer.

    Exemple : Comment récupérer l'état de la visionneuse durant son 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.

    Démarrage rapide

    Appliquer

    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
    onProceedCheckout

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

    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