Custom JavaScript quickstart

The Custom JavaScript integration adds virtual.fit to any storefront that can load a hosted script. Your virtual.fit settings control product availability, shopper access, and daily limits.

Prerequisites

Before installing the loader, you need:

A custom storefront site in virtual.fit.
Its public site key and hosted loader URL.
An exact production or staging origin.
One synced, enabled product with usable garment images.
A CSS selector for the main product media wrapper.

The site key is public and belongs in browser code. Management API keys are secret and must never be embedded in the storefront.

1. Allow the storefront origin

In virtual.fit, open Custom JS → Installation. Add each origin that will load the widget or send analytics.

https://shop.example.com
https://staging-shop.example.com

An origin is the scheme, hostname, and optional port. Do not include paths, query strings, or trailing product URLs.

Page URL	Allowed origin
`https://shop.example.com/products/linen-dress`	`https://shop.example.com`
`https://staging.example.com:8443/p/sku-42`	`https://staging.example.com:8443`

2. Sync and enable one product

Use a CSV import or the management API to add a product. Its handle or product_id must match the value your product URL exposes. For /products/linen-midi-dress, a typical record uses:

{
  "product_id": "sku-10042",
  "handle": "linen-midi-dress",
  "title": "Linen Midi Dress",
  "product_image_urls": [
    "https://cdn.example.com/linen-midi-dress-front.jpg",
    "https://cdn.example.com/linen-midi-dress-back.jpg"
  ],
  "enabled": true
}

See Sync the catalog for CSV and API details.

3. Configure product URL detection

For a URL such as https://shop.example.com/products/linen-midi-dress:

Set Resolution Mode to Path template.
Set Match Products By to Handle.
Set Path Template to /products/:handle.

Paste a real product URL into the virtual.fit live URL tester. Continue only when it reports an enabled matched product.

4. Install the loader

Copy the generated snippet from virtual.fit. The basic pattern is:

<script>
  window.bitstudio = window.bitstudio || function () {
    (window.bitstudio.q = window.bitstudio.q || []).push(arguments);
  };

  bitstudio('init', {
    siteKey: 'site_pub_your_key',
    mount: '.product-media',
    terms: {
      fullSelector: '#virtual-fit-terms'
    }
  });
</script>
<script async src="COPY_THE_SCRIPT_URL_FROM_VIRTUAL_FIT"></script>

Place the snippet on product pages, usually before </body>. Use the exact site key and script URL shown in virtual.fit.

window.bitstudio is the stable browser API name retained for integration compatibility. Use virtual.fit in all merchant and shopper-facing copy.

Choose the mount target

Point mount at the main product gallery or media wrapper. Good targets:

.product-media
.product-gallery
[data-product-gallery]

Avoid the buy box, product form, add-to-cart button, cart drawer, recommendations, and elements that disappear on variant change.

5. Provide full terms markup

If you use fullSelector, add a hidden element whose innerHTML the widget can display:

<div id="virtual-fit-terms" hidden>
  <p>
    By continuing, you confirm that you have the right to use this photo and agree
    to this store's virtual try-on terms.
  </p>
</div>

You can instead provide terms.fullHtml directly. See Styling, labels, and terms.

6. Verify the integration

Open the real product URL and confirm:

The Try On control appears once.
A disabled or unknown product does not show the control.
The widget is positioned over the main product media.
A photo can be uploaded and a try-on completes.
The generated image appears under Results in virtual.fit.

Your first integration is complete when one enabled product passes the full launch checklist.

Custom JavaScript quickstart

Prerequisites

1. Allow the storefront origin

2. Sync and enable one product

3. Configure product URL detection

4. Install the loader

Choose the mount target

5. Provide full terms markup

6. Verify the integration

Next steps

Configure the loader

Track commerce

​Prerequisites

​1. Allow the storefront origin

​2. Sync and enable one product

​3. Configure product URL detection

​4. Install the loader

​Choose the mount target

​5. Provide full terms markup

​6. Verify the integration

​Next steps

Configure the loader

Track commerce

Prerequisites

1. Allow the storefront origin

2. Sync and enable one product

3. Configure product URL detection

4. Install the loader

Choose the mount target

5. Provide full terms markup

6. Verify the integration

Next steps