For the complete documentation index, see llms.txt. This page is also available as Markdown.

Installation & Integration

Virtual Try On is an AI-based project that allows the customer to try on the relevant product on a photo they have uploaded. The flow is completed through 3 core applications:

  • Virtual Try On Extension

  • Frontend (Next or Python)

  • Mobile App


1. Installation

Extension

Variable
Value / Description

DB_SSL

true

DB_SCHEMA

.public

APP_TEST_MODE

false

APP_SERVER_PORT

:8008

SEC_API_AUTH_PASSWORD

20-character combination of uppercase, lowercase letters and numbers (must be entered as a secret)

API_AUTH_USERNAME

15-character combination of uppercase, lowercase letters and numbers

PROCESS_MONITORING

false

GOOGLE_OAUTH_ADDRESS

https://oauth2.googleapis.com/token

APP_LIMITED_CATEGORIES

Comma-separated FE category IDs for categories where try-on should be disabled

APP_SERVER_ACCESS_LOGS

true

VERTEX_AI_IMAGE_FORMAT

base64

INF_TRY_ON_RATE_LIMITER

250-M

API_ALLOWED_IMAGE_DOMAINS

Root domain names of the CDNs where product images are hosted (e.g. akinoncloud.com)

DB_CONNECTION_POOL_MAX_SIZE

20

DB_CONNECTION_POOL_MIN_SIZE

10

TOGGLE_IMAGE_GENERATION_ENABLED

true

S3_PRESIGN_EXPIRE_MINUTES

30

S3_PRESIGN_LISTING_EXPIRE_MINUTES

300

FE-Next

(To be filled)

FE-Python

(To be filled)

Mobile App

This feature is available for projects using env6.1.0 or higher.

Two entry points are provided by the framework:

  • Product Detail Page: single-product try-on via the VirtualTry button.

  • Basket Page: multi-product try-on ("Virtual Cabin") via MultipleVirtualTryButton, letting the user select up to 3 products from their basket to try on together.

Before any photo is uploaded, the user must accept an explicit consent text (CONTRACT_TEXT) covering AI-based processing of their photo. This text is brand-owned copy, not framework boilerplate — each brand must review and localize it before release, since it is a legal/consent statement, not a UI label.

Platform Setup

Android Configuration

Add the required permission to the akinon.json file for Android:

iOS Configuration

Add the required permissions to the akinon.json file for iOS:

By default, a new project's akinon.json has android.permissions: [] and no ios.infoPlist key at all — both must be added explicitly.

Project Setup

Projects created on env6.1.0 or later already include these files and config; verify each item below rather than adding it from scratch. Projects upgraded from an earlier env need to add what's missing.

1. Default Styles, Text and Theme Config

Add and register the following files (the full file diff for the env6.1.0 upgrade, where this feature was introduced, is available at abp.akinon.net/upgrade-helper):

  • src/staticTextMaps/virtualTryOn.json: all VTO copy (button labels, consent text, feedback, tooltips, tips for a good photo, etc.)

  • src/styles/virtualTryOn/gridElements.js and src/styles/virtualTryOn/index.js: VTO styles

  • src/themeConfigs/virtualTryOn.js: grid sizing for product selection / product list / product detail image containers

Register the new style and theme modules in the project's aggregators:

Permission and cropper texts — the permission-denied alerts and native cropper shown by VTO's camera/gallery picker (see useVirtualTry.js) read the following keys. Define them directly in src/staticTextMaps/virtualTryOn.json:

  • NO_CAMERA_PERMISSION_TITTLE / NO_CAMERA_PERMISSION_MESSAGE

  • NO_GALLERY_PERMISSION_TITTLE / NO_GALLERY_PERMISSION_MESSAGE

  • CANCEL, SETTINGS

  • CROPPER_TOOLBAR_TITLE, IOS_CROPPER_CANCEL_TEXT, IOS_CROPPER_CHOOSE_TEXT

2. Icon Configuration

VTO's components reference the following Icomoon icon names — add any that are missing from the project's icon font:

  • camera

  • gallery

  • check

  • thumbs-up

  • thumbs-down

  • virtual-try

  • retry

3. API Endpoint Configuration

Add the Virtual Try On Extension endpoints to src/integrationMaps/urls.json:

VIRTUAL_TRY_WIDGET is an Omnitron widget key, not a URL — keep its value as-is (see Visibility Control below).

Replace <your-vto-extension-host> with the brand's own Virtual Try On Extension deployment; do not ship the shared/demo host used during development.

The flow also relies on two endpoints that don't share the VIRTUAL_TRY* prefix and are easy to miss:

4. Basket Extra Data Configuration

The multi-product flow needs each basket product's image data. Add productimage_set to the PRODUCT config's EXTRA_DATA in src/integrationMaps/basket.json:

If productMapper is overridden in src/dataContainers/basket/model/index.js, add the same EXTRA_DATA entry there as well.

Visibility Control

VTO buttons can be toggled via an Omnitron widget, keyed mobile-virtual-try-status (the VIRTUAL_TRY_WIDGET value above). If the widget is not configured in Omnitron, the buttons are visible by default — this is the mechanism for staged/observation-mode rollout on mobile.

Create the widget in Omnitron with this schema:

A single show field, dropdown type, with "Active" (true) / "Inactive" (false) choices. Setting it to "Inactive" hides the buttons; "Active" (or leaving the widget unconfigured) keeps them visible.

Implementation Guide

Product Detail Page Implementation

In src/pages/productDetail/index.js, import and use the VirtualTry (single try-on) component:

Props:

Prop
Type
Required
Description

product

Object

Yes

The current product; used to launch the single try-on flow.

content

Function/Node

No

Overrides the default button content.

onPress

Function

No

Overrides the default press handler.

checkboxModalContent

Function/Node

No

Overrides the consent checkbox modal content.

checkboxContent

Function/Node

No

Overrides the consent checkbox content.

bottomSheetContent

Function/Node

No

Overrides the consent bottom sheet content.

Basket Page Implementation

In src/pages/basket/index.js, import and use the MultipleVirtualTryButton component:

products is the basket's product list, taken from the basket data container's state (not a plain page prop).

Props:

Prop
Type
Required
Description

products

Array

Yes

Basket products eligible for try-on; the user selects up to 3.

bottomSheetContent

Function/Node

No

Overrides the consent bottom sheet content.

checkboxContent

Function/Node

No

Overrides the consent checkbox content.

checkboxModalContent

Function/Node

No

Overrides the consent checkbox modal content.


2. Observation Mode Controls

Before the application is fully released to end customers, controls must be performed in observation mode. In a deployment made in this mode, end customers cannot directly see the new features. However, the features become accessible when enable_virtual_try_on=true is added to the browser's local storage.

Comprehensive controls must be performed including:

  • Query speed for both direct queries using the product's existing image and queries made with cropping

  • Similar product checks

  • Error checks


3. Release to End Customer

Once the controls are completed, the FE applications must make the feature available to end customers either by deploying a new release or by making a parameter change.

Last updated

Was this helpful?