---
title: "Shoes & Bags AR Try-On — SDK & Integration Guide"
product: "ar-tryon"
last_updated: "2026-09-22"
description: "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..."
---


# 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

```html
<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:

```css
#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:

```javascript
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. Does not disable cross-origin isolation (COOP/COEP are always set on viewer and asset responses). |

#### 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`:

```javascript
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:

```javascript
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. Viewer Options

| Parameter | Type | Description |
|-----------|------|-------------|
| `product_url` | string | Product URL passed through for metadata and deep-linking. |
| `no_height_selector_ui` | boolean | Hide the height selector UI. |

### 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.