How to migrate your integration to v. 10?
New library script
Please import the following new script to use the virtual try-on module on your website:
<script src="//vto-advanced-integration-api.fittingbox.com/index.js" type="text/javascript"/>
The script must be imported only once and synchronously (no `defer` or `async` loading).
Instantiating
As before, the instantiation is done by calling the constructor, `FitMix.createWidget`.
The signature did not change. It takes the same parameters: a parent HTML element in which the VTO module will be embedded, initialisation parameters and a callback triggered when the VTO module is ready to be used.
This callback is important as it will inform the integration that the `startVto` method can be called (as the module is ready).
The module is related to the variable and will thus live only as long as its scope is valid.
For an optimal experience, we advise instantiating the VTO module as soon as possible in the scope and only once per scope, using the same instance.
Some initialisation parameters have changed.
The previous "sku" has been renamed to "frame" to better reflect the use of any kind of frame identifier.
Please refer to the Changelog article for the complete list of changes.
Controlling the virtual try-on experience
startVto()
fitmixInstance.startVto('live' | 'photo' | 'faceshape') : void;
The `startVto` method notifies the VTO module to start a VTO experience, which will result in opening the camera, starting the protocols and providing a VTO experience to the user. The method takes a mode as parameter, to inform whether you want to start an experience in ‘live’ or ‘photo’ mode (or 'faceshape', available with the Face Shape API module).
It is mandatory to wait for the initialisation callback to be triggered before calling the `startVto` method.
The integration is responsible for managing the visibility of the HTML element, in order to display the parent element when the `startVto` is called and hide it when the `stopVto` is called (and once the `onStopVto` callback is triggered).
Here is a pseudo-code example:
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;
The `stopVto` method notifies the VTO module to stop the VTO experience, thus closing the camera and releasing its handle. It is recommended to wait for the `onStopVto` callback to be triggered before hiding the HTML element.
Automatic start
Although we advise instantiating the VTO module in advance to prepare processings and provide a better user experience, it is still possible to instantiate the VTO module on the fly and start it automatically, similarly to the behavior in v. 9. To do so, call the `startVto` directly in the initialisation callback.
fitmixInstance = FitMix.createWidget(parent, params, () => { fitmixInstance.startVto('live'); });
Want to check that you properly migrated to v. 10?
Look for the following console log after you instantiated the VTO module:
VTO Advanced (Fitmix) v. 10.y.zChecking frame availability
Endpoint: product-api.fittingbox.com/glasses-metadata/availability
The request takes the following parameters:
- apiKey: string (required), your apiKey for the VTO Advanced product
- uidList: string (required), a list of frame identifiers (skus, EANs, UPCs, GTINs), comma-separated
The endpoint is limited to batches of 100 frames per call.
The request answers a JSON payload with, for each frame, its availability status.
Here is a response example:
[
{ "uid": [REQUESTED_ID_#1], "available": true/false },
{ "uid": [REQUESTED_ID_#2], "available": true/false },
...
]
We recommend calling this endpoint with batches of a few tens of frames, for instance corresponding to a Catalog page being shown to the user.
Here is a pseudo-code example on how to use the `availability` endpoint to condition the display of a CTA button:
<!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>