Shoes & Bags AR Try-On — SDK & Integration Guide

This guide covers all aspects of embedding the WEARFITS Shoes & Bags AR Try-On viewer into a website or application: iframe setup, the full URL parameter reference, real-time communication via the postMessage API, partner-specific modes, and ready-to-use example URLs.

---

1. Iframe Embedding

The fastest integration path is a standard HTML <iframe>. No JavaScript is required for basic usage.

Basic Implementation

<iframe 
    src="https://app.wearfits.com/tryon?object=YOUR_OBJECT_ID&pose=1&mm=3" 
    allow="camera; display-capture; autoplay; clipboard-write; encrypted-media; fullscreen"
    style="width: 100%; height: 600px; border: none;"
    id="wearfits-viewer">
</iframe>

Replace YOUR_OBJECT_ID with the ID of the 3D model you want to display. The pose=1 parameter activates pose/hand detection, and mm=3 selects mirror mode.

Best Practices

Permissions — The allow attribute must include camera (and the other listed tokens) for pose detection to work. If the attribute is omitted, the browser blocks camera access and the try-on will not function.

Responsive design — For a portrait-oriented viewer that fills its container, use:

#wearfits-viewer {
    width: 100%;
    aspect-ratio: 9 / 16;
    border: none;
}

Dynamic initialization — You can load an empty viewer first (omit the object parameter) and then push a load_object message after the page has loaded. This is useful when the model ID is determined at runtime or needs to change without reloading the iframe:

const iframe = document.getElementById('wearfits-viewer');
iframe.contentWindow.postMessage(
    JSON.stringify({ name: 'load_object', data: 'sneaker_v1', pose: false }),
    '*'
);

---

2. URL Parameters

All parameters are appended to the viewer URL as standard query string key=value pairs, separated by &. Boolean parameters accept 1 (true) or 0 (false). Parameter names are case-sensitive.

Core Parameters

Parameter	Type	Default	Description
object / objects / name	string	—	Unique ID of the 3D model to load.
pose	boolean	0	Enable pose detection mode (required for accessories/bags try-on).
handpose	boolean	0	Enable dedicated hand pose detection.
mm / mirror_mode	integer	1	Mirror mode (1: Front, 2: Back, 3: Mirror, 4–5: additional modes).
lang	string	en	UI language code. Supported values include en, pl, lt, lv, cs, sk, de, and others.
quality	string	medium	Rendering quality: low, medium, or high.
object_scale	float	1.0	Scale factor applied to the loaded 3D object.
preset / color	string	default	Initial color or material preset for the model.

UI Configuration

Hide / Show Toggles

Parameter	Type	Default	Description
nologo	boolean	0	Hide the WEARFITS logo.
noloader	boolean	0	Hide the loading progress bar.
nocolorlist	boolean	0	Hide the material/color preset selector.
noar	boolean	0	Disable the AR launch button.
nopopup	boolean	0	Disable popup windows.
nopan	boolean	0	Disable pan controls.
nozoom	boolean	0	Disable zoom controls.

Additional UI Elements

Parameter	Type	Default	Description
raybutton	boolean	0	Show the ray-tracing quality toggle button.
showquality	boolean	0	Show the quality selector in the viewer UI.
showrotation	boolean	0	Show rotation controls.
resizable	boolean	0	Make the AR popup window resizable.
settings	boolean	0	Show the advanced settings panel (includes video recording controls).
height_selector	boolean	0	Show the height input UI when pose=1 is active.

Display Customization

Parameter	Type	Default	Description
background	string	—	Background environment preset (e.g., studio).
background_texture_color	string	—	Background texture color as a hex value (e.g., #ffffff).
zoomfactor	float	1.0	Initial zoom level applied to the 3D view.
controlstype	string	orbit	Camera controls type: orbit or trackball.

Performance & ML

Turbo & Async Modes

Parameter	Type	Default	Added	Description
turbo	boolean	0	Aug 2025	Enable Turbo mode: alternates the ML and optical-flow pipelines with a strict 2-frame delay. Forces buffer=3 and disables automatic buffer tuning while active. Optimized for high-FPS footwear try-on.
no_logs	boolean	0	Jul 2025	Disable worker logging for improved runtime performance.
async_mode	boolean	0	—	Enable asynchronous ML processing.

Native ML

Parameter	Type	Default	Description
native_ml	boolean	0	Use native WASM-based ML instead of TensorFlow.js WebGL. Improves performance on some devices.
native_ml_size	integer	192	Native ML model input size. Valid values: 160, 192, 256. Larger values increase accuracy at the cost of speed.
native_ml_point_set	integer	0	Point set variant for the native ML model.

Pose Detection Quality

Parameter	Type	Default	Added	Description
pose_quality	integer	2	Aug 2025	Pose model quality level: 1 = lite, 2 = full, 3 = heavy.
target_pin_location	string	left_hand	Jul 2025	Pin attachment location. Pass auto to enable dynamic hand switching based on which hand is detected.
ignore_unstable_movements	boolean	true	May 2025	Filter out violent or unstable motion to prevent jitter. Set to 0 to disable.
oflow_error_threshold	float	10.0	Jun 2025	Optical flow error filtering threshold (range 0–100). Higher values accept noisier motion estimates.

ML Backend Selection

Parameter	Type	Default	Description
tf_backend	string	webgl	TensorFlow.js compute backend: webgl, cpu, or wasm.
onnx_backend	string	webgl	ONNX Runtime compute backend.
onnx	boolean	0	Use ONNX Runtime instead of TensorFlow.js.
webnn	boolean	0	Enable WebNN hardware acceleration (where supported).
litert	boolean	0	Enable LiteRT (TensorFlow Lite) backend.
threads	integer	—	Number of worker threads allocated for ML processing.
ml_model_url	string	—	URL to a custom ML model definition file.
compute_mode	string	—	Computation mode: javascript, worker, native, or server.

Model Selection

Parameter	Type	Default	Description
masks / use_additional_masking_model	boolean	0	Enable additional segmentation masking models.
corp	boolean	0	Corporate model configuration.

Camera & Resolution

Parameter	Type	Default	Description
res	string	—	Requested camera resolution, e.g., 1280x720.
user_height	integer	—	User height in centimeters. Pre-fills the height calibration field.

Processing Options

Parameter	Type	Default	Description
origin	string	—	Custom CDN origin URL for 3D assets.
partner	string	—	Partner identifier string passed to the backend.
object_collection_id	string	—	Collection identifier for grouped model sets (e.g., summer2024).

AR Configuration

AR Mode

Parameter	Type	Default	Description
viewar	boolean	0	Enable AR view mode.
webar / webxr	boolean	0	Enable WebAR / WebXR mode.
platform	string	—	Platform hint: iOS or Android. Used to select the appropriate AR launch path.
vertical	boolean	0	Use vertical AR orientation.
sound	string	—	Sound settings for AR experiences.

AR Metadata (Custom Branding)

Parameter	Type	Default	Description
ar_title	string	WearFits	Title displayed in the AR popup / share card. Set to your product name.
ar_link	string	—	Product URL shown in the AR popup, linking back to your shop.
user_id	string	—	User identifier passed through for analytics or personalization.

Fitting Room Parameters

These parameters apply to the 3D Fitting Room endpoint rather than the live try-on viewer.

Avatar & Garment

Parameter	Type	Default	Description
garmentid	string	—	Garment identifier.
avatarid	string	—	Avatar identifier.
avatarpreset	string	default	Avatar body preset (e.g., athletic).
size	string	—	Garment size to display.
hash	string	—	Avatar hash for pre-built avatars.

Fitting Room UI Toggles

Parameter	Type	Default	Description
nosizeselection	boolean	0	Hide the size selection UI.
noavatarselection	boolean	0	Hide the avatar selection UI.
nocomfortbutton	boolean	0	Hide the comfort indicator button.
norenderbutton	boolean	0	Hide the render button.
nofittext	boolean	0	Hide fit description text.
allsizesview	boolean	0	Show all sizes simultaneously.
strainmode	boolean	0	Enable strain / pressure visualization on the garment.
noinit	boolean	0	Skip initialization sequence.

Fitting Room Scene

Parameter	Type	Default	Description
scene	string	—	Scene type (e.g., studio).
viewrl	boolean	0	Enable right-left split view.

Debug & Development

Parameter	Type	Default	Description
debug	boolean	0	Enable debug mode with on-screen diagnostics.
settings	boolean	0	Show advanced settings panel.
progress	boolean	0	Show detailed progress indicators.
version	string	—	Version identifier string (e.g., dev).
nocamera	boolean	0	Disable camera input. Useful for testing with static images.
log_url	string	—	URL of a bug report log file. The app will replay the configuration described in the log.
is_object_for_tryon	boolean	0	Mark object for try-on compatibility testing.
photogrammetry_id	string	—	Photogrammetry task identifier.
try_number	integer	0	Try attempt counter (used in automated testing).
erasing	float	—	Erasing threshold for segmentation masking.
smoothing	integer	—	General smoothing factor applied to detection keypoints.
mask_smooth	integer	—	Smoothing factor applied specifically to segmentation masks.

Localization

Parameter	Type	Default	Description
lang	string	en	Language code. Supported: en, pl, lt, lv, cs, sk, de, and additional locales.

---

3. Communication — postMessage API

The postMessage API allows the host page to control the viewer and receive events from it in real time, without reloading the iframe.

Sending Commands TO Wearfits

Serialize the command as JSON and post it to the iframe's contentWindow:

const iframe = document.getElementById('wearfits-viewer');
iframe.contentWindow.postMessage(JSON.stringify(payload), '*');

Command	Payload	Description
load_object	{ data: "MODEL_ID", pose: bool }	Load a new 3D model. Set pose: true for accessories/bags mode, pose: false for footwear mode.
enable_camera	{ data: bool }	Start (true) or stop (false) the camera stream.
set_option	{ key: "propertyName", value: any }	Directly set a property in the internal tryon_app_config object. Triggers the internal setOption callback.
show_user_height_popup	{}	Display the height selection / calibration UI.
close_user_height_popup	{}	Hide the height selection UI.

Receiving Events FROM Wearfits

The viewer emits events via window.postMessage. Events are wrapped in a wearfitsEvent envelope. Add a listener on the host page:

window.addEventListener('message', (event) => {
    let payload;
    try {
        payload = JSON.parse(event.data);
    } catch (e) {
        return;
    }

    if (payload.name === 'wearfitsEvent') {
        const { name, data } = payload.data;
        console.log('SDK Event:', name, data);

        switch (name) {
            case 'loadingFinishedHandler':
                // Viewer is fully ready
                break;
            case 'objectLoadingFinishedHandler':
                // A model has finished loading
                break;
            case 'objectVisibilityChangedHandler':
                // Model detection state changed — data is bool
                break;
        }
    }
});

Full SDK Event Reference

Event Name	Data	Description
scene_load	null	The 3D scene (lights, camera, renderer) has been initialized.
loadingFinishedHandler	error_code (optional)	Initial application setup is fully complete and the viewer is ready.
loadingProgressHandler	percent (0–100)	Progress update during application initialization.
objectLoadingProgressHandler	percent (0–100)	Download progress for the current 3D model.
objectLoadingFinishedHandler	obj_data	A 3D model has finished loading. obj_data contains metadata about the loaded object.
objectVisibilityChangedHandler	bool	The 3D model entered or left the camera frame (general).
shoesVisibilityChangedHandler	bool	Footwear-specific visibility event: shoe detected (true) or lost (false).
userHeightSelectedHandler	height_cm	The user confirmed their height in the calibration popup.
heightSelectorVisibilityChangedHandler	bool	The height selection UI was shown (true) or hidden (false).
record_output_finished	{ blob, file_size, … }	A video recording (.mp4) has been finalized and is ready.
configureCalibrationPhase	string	Current calibration phase descriptor (e.g., "countdown", "data_collection").
configureCalibrationFinished	null	Calibration completed successfully.
configureCalibrationFailed	null	Calibration failed.
setOption	{ key, value }	Acknowledgment that a set_option command was applied.

---

4. Partner Integrations

Zara

The Zara integration is available at the dedicated endpoint /tryon/zara, or can be activated on the standard endpoint with shop=zara. Additional Zara-specific parameters:

Parameter	Type	Description
zara_endpoint	string	Custom Zara API endpoint URL.
no_height_selector_ui	boolean	Hide the height selector UI in Zara mode.

Nanovo

Parameter	Type	Description
nanovo_scope	string	Nanovo scope identifier (e.g., footwear).

Other Partners

Parameter	Type	Description
shop	string	Generic shop/retailer identifier (e.g., ?shop=retailer123).
product_url	string	Product URL passed through for metadata and deep-linking.

Mirror Mode (Kiosk)

The mirror mode setting (mm / mirror_mode) is designed for in-store kiosk deployments and large-screen installations. Use mm=3 (mirror) for a natural reflection experience, combined with nologo=1 and nopopup=1 to create a clean, fullscreen kiosk UI.

For custom branding or white-label solutions, contact the WEARFITS team.

---

5. Usage Examples

Basic Try-On

Load a specific shoe model with pose detection and mirror mode:

/tryon?object=sneaker_v1&pose=1&mm=3

High-Quality Pose Detection

Maximum pose accuracy with automatic hand switching:

/tryon?pose=1&pose_quality=3&target_pin_location=auto&ignore_unstable_movements=1

Performance Optimized

Reduced logging overhead with native WASM ML at maximum model size:

/tryon?no_logs=1&async_mode=1&native_ml=1&native_ml_size=256

AR with Custom Branding

AR viewer with product name, shop link, and WEARFITS logo hidden:

/viewAR?object=watch_001&ar_title=Luxury%20Watch&ar_link=https%3A%2F%2Fshop.com%2Fwatch&nologo=1

Turbo Mode

High-FPS footwear try-on with alternating ML/optical-flow pipeline:

/tryon?turbo=1

Debug Mode

Full development overlay with settings panel and progress indicators:

/tryon?debug=1&settings=1&progress=1&version=dev

---

Notes

• Boolean parameters: Use 1 for true, 0 for false.
• Case sensitivity: All parameter names are case-sensitive.
• Combining parameters: Separate multiple parameters with &.
• URL encoding: Encode special characters in parameter values (e.g., spaces as %20, # as %23).
• Browser compatibility: WebXR, WebNN, and certain ML backends may not be available in all browsers. The viewer falls back gracefully where features are unsupported.