API Reference
List of all the existing methods and parameters of the Virtual Try-On
Instance methods
addCss(styles: string): void
Adds customized CSS rules in the VTO module underlying `iframe`.
getSnapshot(): void
Takes a snapshot of the VTO module video feed.
The result of the snapshot is retrieved in the `onSnapshot` callback.
Can only be used in Live mode.
resetDisclaimer(): void
Removes the status of the disclaimer in the local storage (see Web Storage).
resetSession(): void
Removes all informations stored in the local storage (see Web Storage).
restartVto(): void
Restarts the VTO protocols.
Should only be called after the starting or the detection protocols failed and the VTO aborted (see the onIssue callback).
setFrame(id: string): void
Changes the current frame being used in the VTO experience.
The `id` is any frame identifier such as an EAN, GTIN, UPC or a SKU.
If the frame identifier is found, the asset is downloaded and then set in the VTO module.
This method does not start the VTO module.
setLang(lang: string): void
Sets the language of the VTO module (see Localization).
setLensesAntireflection(enable: boolean): void
Enables or disables the anti-reflection filter on lenses in the VTO module.
setMode(mode: string): boolean
Changes the current mode of the VTO module.
`mode` can be `live`, `photo` (or `faceshape` when the Faceshape module is activated).
This method does not start the VTO module.
setPupillaryDistance(pupillaryDistance: number): void
Updates the pupillary distance used for the try-on positioning.
If set, the `pupillaryDistance` value will be used to override the default value (default value = 63mm).
setTryonPicture(imgData: string): void
Sets the picture to be used in the VTO module when in `photo` mode.
`imgData` should contain a Base64 encoded image.
This triggers a new photo VTO try-on.
setUiConfiguration(data: object): void
Enables or disables the different UI element in the VTO module.
`data` is an object with the following fields:
data: {
apiKeyIssueMessage: boolean;
frameIssueMessage: boolean;
liveCameraAccessDenied: boolean;
liveDetectionFailure: boolean;
liveLensesAnimations: boolean;
livePhotoButton: boolean;
liveRelaunchDetectionButton: boolean;
loadingIndicator: boolean;
networkIssueMessage: boolean;
photoLiveButton: boolean;
photoRenderError: boolean;
photoWelcomeScreen: boolean;
positioningGuideOverlay: boolean;
cameraPermissionScreen: boolean;
vtoLoadingScreen: boolean;
hideEverything: boolean;
}
setUserInfo(data: object): void
Updates user information, such as the gender and/or the pupillary distance.
If set, the `gender` attribute is used to set an average pupillary distance value of 62mm for `f = female` and 64mm for `m = male`. Similarly, if set, the `pupillaryDistance` value will be used to override the default value (default value = 63mm).
`data` is an object with the following fields:
data: { gender?: "f" | "m", pupillaryDistance?: number }
setZoomFactor(zoomFactor: number): void
Zooms in the camera feed.
startVto(mode: string): void
Starts the VTO module in the specified `mode`.
`mode` can be `live`, `photo` (or `faceshape` when the Faceshape module is activated).
For `mode` == `live` (and `faceshape`), this will result in the camera feed being opened which will prompt, if needed, the user for camera access and switch on the camera access indicators.
stopVto(): void
Stops the VTO module.
When the current mode is `live` (or `faceshape`), this will result in the camera feed being closed, which will switch off the camera access indicators.
Instance callbacks
onAgreePrivacyTerms: () => void
Triggered when the user agrees the privacy terms or if the privacy terms are accepted in the local storage.
onDisagreePrivacyTerms: () => void
Triggered when the user disagrees the privacy terms.
onIssue: (data: object) => void
Triggered when an issue is impairing the user experience (see related How-to guide).
`data` is an object with the following field:
data: {
cameraAccessDenied: boolean;
detectionFailed: boolean;
frameNotFound: boolean;
highLatency: boolean;
licenseNotFound: boolean;
liveIncompatibleBrowser: boolean;
liveIncompatibleOS: boolean;
noCameraFound: boolean;
poseInvalid: boolean;
protocolFailed: boolean;
removalLowPerformances: boolean;
serverNotResponding: boolean;
trackingLost: boolean;
}
onLiveStatus: (data: onLiveStatusType) => void
Triggered when the status of the VTO module in `live` mode changes (see related How-to guide).
`data` is an object with the following fields:
data: {
faceTracking: boolean; // Is the user's face tracked
glassesReady: boolean; // Is the digital frame ready to be displayed
hasStream: boolean; // Is the camera stream opened
removalActive: boolean; // Is the Frame Removal module active
userHasGlasses: boolean; // Is the digital frame displayed in VTO
}
onMode (mode: string): void
Triggered when the VTO module switches to the corresponding `mode`mode
`mode`can be : "live", "photo", "viewer" or "faceshape".
This may happen when a change of mode is requested programmatically or when the user changes mode via a UI in the VTO.
onOpenStream: (value: { success: boolean }) => void
Triggered when the camera feed is successfully opened and is displayed in the VTO module.
onPhotoRender: (result: object) => void
Triggered when a requested photo VTO render has been processed and the response is received.
This coincides with the render being displayed in the VTO module (if the render has been successful).
`data` is an object with the following fields:
data: {
success: boolean;
frame: string;
data: string; // rendered image in base64
errorDetail: string;
}
onPrivacyTermsShown: () => void
Triggered when the privacy terms are shown in the VTO module.
This callback is not triggered when the privacy terms are accepted in the local storage.
onSnapshot: (data: onSnapshotType) => void
Triggered after a call to `getSnapshot`, when the image is available.
`data` is an object with the following fields:
data: {
dataUrl: string; // image in base64
height: number;
width: number;
}
onStopVto: () => void
Triggered when the VTO module has been correctly stopped, i.e. the camera has been properly released.
onUiStatus: (data: onUiStatusType) => void
Triggered on any UI element visibility change.
`data` is an object with the following fields:
data: {
apiKeyIssueMessage: boolean;
badQualityError: boolean;
cameraPermissionScreen: boolean;
frameIssueMessage: boolean;
liveCameraAccessDenied: boolean;
liveDetectionFailure: boolean;
liveRelaunchDetectionButton: boolean;
loadingIndicator: boolean;
modeSwitchButton: boolean;
networkIssueMessage: boolean;
photoRenderError: boolean;
photoWelcomeScreen: boolean;
positioningGuideOverlay: boolean;
removalAdjustmentArrows: boolean;
vtoLoadingScreen: boolean;
}
Native “Add to cart” button: This feature allows you to display a native call-to-action in the VTO interface and choose the redirection needed for your user flows.
{
onAddToCartButtonClicked?: (data: { frameId?: string; material?: string }) => void;
"addToCartSettings": {
"addToCartButtonLabel": "string",
"addToCartButtonIcon": "string"
}
}
Native Frame Carousel: This feature allows you to display recommended frames and frame variants (color, size, lens color) directly inside the VTO selector.
Required fields must be provided for items to be displayed in the carousel.
{
"carousel": {
"frames": [
{
"frameLabel": "string",
"frameImageUrl": "string",
"frameAdditionalInfo": "string",
"variants": [
{
"variantLabel": "string",
"variantThumbnailUrl": "string",
"sizes": [
{
"sizeLabel": "string",
"frameId": "string"
}
]
}
]
}
],
"lenses": [
{
"lensId": "string",
"lensLabel": "string",
"lensImageUrl": "string"
}
]
settings: {
recommendedSectionTitle: "string"
}
}
}
Instantiation parameters
apiKey: string (mandatory)
Sets the `apikey` used in the VTO module to check the license informations.
css: string
Adds custom CSS rules to the VTO module to override default style.
dataPrivacyDisclaimerTexts: object
Changes the different texts used in the privacy terms.
The value is an object with the following fields:
{
longText?: string;
agreeButton?: string;
disagreeButton?: string;
}
frame: string
Sets the frame to load for the VTO experience.
The `id` is any frame identifier such as an EAN, GTIN, UPC or a SKU.
If the frame identifier is found, the asset is downloaded and then set in the VTO module.
height: number
Sets the height of the VTO module underlying `iframe`.
lang: string
Sets the language of the VTO module (see Localization).
If `lang` is not set, the VTO module will use a default language based on the browser settings (see Localization).
popupIntegration: object
Sets the VTO module to be opened in a native pop-up.
The value is an object with the following fields:
{
centeredHorizontal: boolean;
centeredVertical: boolean;
height: number | string;
horizontal: string {'left', 'right'};
horizontalOffset: string; // Ex: '10px'
vertical: string {'top', 'bottom'};
verticalOffset: string; // Ex: '10px'
width: number | string;
}
uiConfiguration: object
Sets the different UI elements' visibility.
The value is an object with the following fields:
{
apiKeyIssueMessage: boolean;
frameIssueMessage: boolean;
liveCameraAccessDenied: boolean;
liveDetectionFailure: boolean;
liveLensesAnimations: boolean;
livePhotoButton: boolean;
liveRelaunchDetectionButton: boolean;
loadingIndicator: boolean;
networkIssueMessage: boolean;
photoLiveButton: boolean;
photoRenderError: boolean;
photoWelcomeScreen: boolean;
positioningGuideOverlay: boolean;
cameraPermissionScreen: boolean;
vtoLoadingScreen: boolean;
hideEverything: boolean;
}
width: number
Sets the width of the VTO module underlying `iframe`.
Product API methods
availability
Checks if a list of frames are available for the product, i.e. if a virtual asset exists to do VTO and if it is compatible with the viewer.
This endpoint is limited to a list of 150 frames per call.
[GET] product-api.fittingbox.com/glasses-metadata/availability
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
Returns a JSON payload with, for each frame, its availability status and viewer compatibility
Example of the result payload:
[
{ "uid": [REQUESTED_ID_#1], "available": true/false, "viewerCompatible": true/false },
{ "uid": [REQUESTED_ID_#2], "available": true/false, "viewerCompatible": true/false },
...
]