Comment migrer votre intégration vers la v. 10 ?
Nouveau script de la bibliothèque
Importez la nouvelle bibliothèque logicielle via l'appel d'import suivant :
<script src="//vto-advanced-integration-api.fittingbox.com/index.js" type="text/javascript">
Le script ne doit être importé qu'une seule fois et de manière synchrone (sans balise de chargement `defer` ou `async`).
Instanciation
L’appel à `FitMix.createWidget()` n’a pas changé. Il prend toujours en paramètres : l'élément HTML dans lequel le module VTO sera affiché, les paramètres d’initialisation et une callback pour effectuer des traitements lorsque le widget est prêt.
La callback passée en paramètre permet à l’intégrateur de réagir au fait que l’instance est correctement initialisée. Il est important d’attendre que cette callback ait été déclenchée avant de demander un potentiel `startVto`.
Le module va vivre tant que le scope de la variable est valide. Pour une intégration optimale, il est conseillé de créer l’instance au plus tôt dans le scope et une seule fois par scope, en ré-utilisant toujours cette même instance.
Les paramètres d'initialisation ont été en partie modifiés.
L'ancien paramètre "sku" a été renommé en "frame" pour mieux refléter le fait de pouvoir passer tous les types d'identifiants de lunettes.
Se référer à la page de Changelog pour la liste exhaustive des changements.
Pilotage du module VTO
startVto()
fitmixInstance.startVto('live' | 'photo' | 'faceshape') : void;
La méthode `startVto` signifie au module VTO de démarrer une expérience VTO, ce qui implique l’ouverture de la caméra pour les modes ‘live' et 'faceshape'. Ensuite, dès lors que le flux caméra est disponible, l’expérience VTO se lance.
Il est important d’attendre que la callback d’initialisation (en paramètre du constructeur) ait été déclenchée pour signifier, à l’intégration, que la méthode `startVto` peut être appelée.
L’intégrateur est responsable de gérer la visibilité de l'élément HTML, pour afficher le VTO Advanced à l’appel de `startVto` et le cacher après l’appel à `stopVto`.
Voici un exemple en pseudo-code :
const fitmix = document.getElementById("fitmix-container")
var params = {
apiKey: '...',
// Use the callback to hide the module when it is properly stopped
onStopVto : () => { fitmix.style.display = 'none'; },
};
function hideVto() {
fitmixInstance.stopVto()
}
function showVto() {
fitmix.style.display = 'block';
fitmixInstance.startVto('live')
}
stopVto()
fitmixInstance.stopVto() : void;
La méthode `stopVto` relâche l’accès à la caméra, ce qui signifie que les indicateurs visuels (dans le navigateur et la diode à côté de la caméra) vont s'éteindre. De plus, les calculs relatifs à l’expérience VTO s’arrête.
Comme pour le démarrage, l’intégrateur est responsable de gérer la visibilité de l'élément HTML pour le cacher. Il faut attendre le retour de la callback `onStopVto`, notifiant que l'arrêt s'est bien fait, pour cacher l'élément.
Démarrage automatique
Bien que nous conseillons d’initialiser le VTO Advanced au plus tôt dans la navigation de la page pour ensuite démarrer l’expérience VTO à la demande de l’utilisateur, il est possible d’avoir un démarrage automatique après l’initialisation, similaire au comportement de la v. 9, en appelant la méthode `startVto` dans la callback d’initialisation, fournie en paramètre du constructeur.
fitmixInstance = FitMix.createWidget(parent, params, () => { fitmixInstance.startVto('live'); });
Contrôle de disponibilité
Endpoint: product-api.fittingbox.com/glasses-metadata/availability
La requête prend en paramètres :
-
apiKey : string (required), votre apikey du VTO Advanced
-
uidList : string (required), une liste des identifiants de paires (skus, UPC, EAN, GTIN), séparés par une virgule
L'endpoint est limité à des listes de 100 paires par appel.
La requête retourne, en résultat, en JSON au format suivant pour indiquer la disponibilité ou non de chaque paire :
[
{ "uid": [REQUESTED_ID_#1], "available": true/false },
{ "uid": [REQUESTED_ID_#2], "available": true/false },
...
]
Nous conseillons d’appeler cet endpoint par groupe de quelques dizaines de produits, par exemple au chargement d’une page catalogue.
Voici un exemple d’appel au endpoint availability pour conditionner la disponibilité d’un bouton CTA de l’expérience VTO :
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Title</title>
</head>
<body>
<script>
/**
* @param {string[]} idTable
* @returns {Promise<{uid: string, available: boolean}[]>}
**/
async function getAvailability(idTable) {
// Put your apiKey as an environment Variable
const apiKey = "apiKey"
const url = `https://product-api.fittingbox.com/glasses-metadata/availability?apiKey=${apiKey}&uidList=${idTable.join(",")}`
const result = await fetch(url)
if (result.ok) {
return result.json()
}
throw new Error("an error occured")
}
/**
* @param availability
* @returns {HTMLElement}
**/
function createCard({available, uid}) {
const container = document.createElement("div")
const button = document.createElement("button")
const title = document.createElement("h3")
title.innerText = uid
// Better use css just easier to show in the doc
title.style.textAlign = "center"
button.style.margin = "auto"
button.style.display = "block"
button.innerHTML = "choose frame"
container.id = uid
container.style.maxWidth = "300px"
container.style.margin = "auto"
container.append(title)
container.append(button)
if(!available) {
button.disabled = true
}
// Could append card on the dom here but i don't like side effects
return container
}
async function main() {
const idTable = ["uid1", "uid2", "uid3", "uid4", "etc"]
try {
const availabilityResult = await getAvailability(idTable)
const cards = availabilityResult.map(createCard)
cards.forEach((card) => { document.body.append(card) })
} catch(err) {
// Handle fetch error
}
}
main()
</script>
</body>
</html>