# WEARFITS Virtual Try-On Widget

Last updated: 2026-09-22.

## Choose the storefront path

For a storefront and the complete try-on UI plus size fitting, the recommended
path is the hosted iframe at https://tryon.wearfits.com/?sizeFitting=true. Follow
https://tryon.wearfits.com/docs/integration.html for READY/INIT and base product
handoff. Put the optional sizeChart sibling field on each
WEARFITS_INIT.payload.products[] item; SET_PRODUCTS uses the same product shape.
The chart requires version 1, basis "body", unit "cm" or "in", and body ranges
for height, chest, waist, hip, or inseam. Test at
https://tryon.wearfits.com/demo_tryon.html; storefront code
exposes no service API key.

The hosted product categories are top, bottom, fullBody, and shoes; the widget
below uses full-body and shoe. Translate those values when switching surfaces.
For iframe messages, verify both event.origin and event.source, and send to
the exact https://tryon.wearfits.com target origin.

Choose the widget only for a lightweight API-backed modal. It does not include
the hosted iframe's size-fitting overlay. If the integrator has explicitly
chosen the widget, continue with the instructions below: it adds try-on with one
script tag, no build step, and no dependencies. For the underlying REST contract
see https://api.wearfits.com/doc.

## Install

```html
<script src="https://api.wearfits.com/widget/tryon.js"
        data-storefront-token="wfs1.…"></script>
```

This defines `window.Wearfits.openTryOn(config)`.

## Open the modal

```html
<button id="wearfits-tryon">Try on</button>
<script>
  document.getElementById('wearfits-tryon').addEventListener('click', function () {
    Wearfits.openTryOn({
      products: [
        {
          id: 'sku-123',
          name: 'White Cotton Shirt',
          category: 'top',
          images: ['https://shop.example/shirt.jpg'],
          sizes: ['S', 'M', 'L'],
          variants: [{ id: 'v1', size: 'M' }]
        }
      ],
      customer: { gender: 'female', height: 170 }
    });
  });
</script>
```

## openTryOn config

| Field | Purpose |
| --- | --- |
| `products` | Array of product objects (see below). `product` accepts a single object. |
| `storefrontToken` | Overrides `data-storefront-token`. Preferred over `apiKey`. |
| `apiKey` | Fallback credential. Do not put a dashboard-issued merchant key here. |
| `apiBase` | Point at a backend proxy instead of calling the API directly. |
| `customer` | Optional `{ gender, height }` to prefill the form. |
| `webhookUrl` | Optional server-to-server completion callback. |

## Product object

`{ id, name, category, images[], sizes[], variants[] }`

With one product, the widget sends its first image as productImage. Categories
auto, top, bottom, full-body, and shoe are supported (dress and shoes are aliases).
A single shoe product therefore supports photo try-on. This is not a live AR viewer.
With multiple products, the first image of each maps to a garment slot:

- `top` -> topGarment
- `bottom` -> bottomGarment
- `full-body` / `dress` -> fullBodyGarment
- `shoe` / `shoes` -> shoes

In the multiple-product path, at least one of top/bottom/full-body is required;
shoes is an add-on. Pass at most one item per slot: later items overwrite earlier
ones. Unknown multiple-product categories fall back to top. sizes and variants
are metadata; this lightweight widget does not provide variant selection or a
size recommendation. The merchant must pass the selected variant's image first.

## What the widget does

1. Renders product cards plus an avatar-input form: saved digitalTwinId, or face
   image plus silhouette image, or face image plus height/clothing size.
2. Validates input client-side, submits the virtual fitting, and polls the job.
3. Persists the returned `digitalTwinId` in `localStorage` for repeat visits.
4. Shows the result image, or a clear error message.

## Security

The widget calls the API directly from the browser. For production, mint a
short-lived storefront token (`POST /api/v1/storefront/tokens`) and put it in
`data-storefront-token`, or set `apiBase` to a backend proxy that injects a
service key plus `X-Wearfits-Account`. Do not embed an account-issued dashboard
key — a shopper can copy it and exhaust the plan. The virtual-fitting and
job-status endpoints are CORS-enabled for cross-origin storefront use; token
minting is not.
Mint tokens from a trusted backend using the merchant credential; never use a
permanent token in a cached theme setting. Refresh before expiry. Reminting for
the same account preserves access to in-flight widget jobs. Browser tokens are
limited to virtual-fitting and job status, and still consume the merchant quota.
For apiBase proxies, the widget appends /api/v1/virtual-fitting and
/api/v1/jobs/{id}. Implement these routes, preserve upstream JSON/status, validate
the storefront session and enforce abuse limits. apiBase does not create a proxy.

For a backend / non-browser integration, see the `wearfits-api-integration`
skill and the OpenAPI spec at https://api.wearfits.com/doc.