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:

{
  "android": {
    "permissions": [
      "android.permission.CAMERA"
    ]
  }
}

iOS Configuration

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

{
  "ios": {
    "infoPlist": {
      "NSCameraUsageDescription": "This app requires camera access to take photos for virtual try-on.",
      "NSPhotoLibraryUsageDescription": "This app requires photo library access to select photos for virtual try-on."
    }
  }
}

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:

// src/styles/index.js
import * as virtualTryOn from './virtualTryOn';

export default {
  // ...existing styles
  virtualTryOn,
};

// src/themeConfigs/index.js
import virtualTryOn from './virtualTryOn';

export default {
  // ...existing theme configs
  virtualTryOn,
};

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_ON": "https://<your-vto-extension-host>/api/v1/virtual-try-on",
  "VIRTUAL_TRY_ON_ASYNC": "https://<your-vto-extension-host>/api/async/v1/virtual-try-on",
  "VIRTUAL_TRY_ON_STATUS": "https://<your-vto-extension-host>/api/async/v1/job-status",
  "MULTIPLE_VIRTUAL_TRY_ON": "https://<your-vto-extension-host>/api/v1/multiple-virtual-try-on",
  "ASYNC_MULTIPLE_VIRTUAL_TRY_ON": "https://<your-vto-extension-host>/api/async/v1/multiple-virtual-try-on",
  "VIRTUAL_TRY_ON_FEEDBACK": "https://<your-vto-extension-host>/api/v1/feedback",
  "VIRTUAL_TRY_ON_LIMITED_CATEGORIES": "https://<your-vto-extension-host>/api/v1/limited-categories",
  "VIRTUAL_TRY_WIDGET": "mobile-virtual-try-status"
}

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:

{
  "GENERATE_BREADCRUMB": "menus/generate_breadcrumb/",
  "PRODUCT_CATEGORY_NODES": "products/$productPk/category_nodes/?limit=1&format=json"
}

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:

 "PRODUCT": {
   "BRAND": "",
   "ATTRIBUTES": [],
   "VARIANTS": [],
-  "EXTRA_DATA": []
+  "EXTRA_DATA": [
+    {
+      "key": "productimage_set",
+      "selector": "product.productimage_set"
+    }
+  ]
 }

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:

{
  "show": {
    "key": "show",
    "label": "Virtual Try Visibility",
    "choices": [
      { "label": "Active", "value": "true" },
      { "label": "Inactive", "value": "false" }
    ],
    "required": true,
    "data_type": "dropdown",
    "is_localizable": false
  }
}

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:

import VirtualTry from "_components/virtualTry/singleVirtualTryButton";

const ProductDetailGrid = (pageContext) => {
  const { product } = pageContext;

  return (
    <VirtualTry
      product={product}
    />
  );
};

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:

import MultipleVirtualTryButton from '_components/virtualTry/multipleVirtualTryButton';

const BasketGrid = (pageContext) => {
  const {
    basket: { products = [] } = {},
  } = pageContext;

  return (
    <MultipleVirtualTryButton
      products={products}
    />
  );
};

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

The product must NEVER be released directly to the end customer without these controls being completed.

---

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.