Add the storefront widget

Add the GenFashion Try it on button to your product pages with one script tag, and build your own front end if you need to.

Updated 7 November 2026

The widget adds a Try it on button to a product page. A shopper taps it, agrees to the consent note, adds a photo and sees the garment on themselves. It is one script with no dependencies and no build step.

Add the button#

Create a publishable key under Settings > API keys and list your store's domains on it. Then paste this next to your Add to bag button:

html

<script src="https://genfashion.buildframe.tech/embed/v1.js"
        data-key="sk_publishable_your_key"
        data-product="shirt-42" defer></script>

data-product is the external ID of the product on that page. The product must already be in your catalogue. Without data-product, no button appears.

Why this key is safe in your page#

Anyone can read a publishable key in your page source. It is protected by its list of allowed domains: a request from any other domain is refused. A key cannot be created with an empty list.

Never put a secret key (sb_secret_) in a page. Secret keys are only for your server.

Options#

Set these as data- attributes on the script tag, or as query parameters on its src.

Attribute	What it does
`data-key`	Your publishable key. Required unless you use `data-proxy`
`data-product`	The product on this page, by external ID
`data-target`	A CSS selector to put the button in, instead of beside the script tag
`data-label`	The button text. The default is "Try it on"
`data-platform`	Set to `shopify` to read the product from the page and place the button next to the add-to-cart form
`data-proxy`	A Shopify app proxy path, such as `/apps/try-on`. The widget then uses a short-lived session instead of a key

To control the widget from your own code:

window.GenFashion.open("shirt-42");      // open the dialog
window.GenFashion.mount(el, "shirt-42"); // add a button to an element
window.GenFashion.shopperId();           // the ID stored for this browser

The file picker stays closed until the shopper ticks a consent box. The box is never ticked in advance, and you cannot change that. The choice is remembered in the browser, and the shopper can withdraw it. Consent travels with each request, and a request without it is refused before the photo is read.

Shopper identity#

Shoppers do not need an account. The widget creates a random ID and keeps it in the browser. It does not survive cleared browser data or a different browser, so if you may need to find a shopper's try-ons later, use a session with your own customer ID. See Privacy and data.

Build your own front end#

For a headless store or a native app, call the endpoint the widget uses:

bash

curl -X POST "https://genfashion.buildframe.tech/api/storefront/v1/try-on" \
  -H "x-api-key: sk_publishable_your_key" \
  -H "X-Shopper-Id: a-stable-id-from-your-front-end" \
  -H "Origin: https://shop.example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "person": "data:image/jpeg;base64,...",
    "productIds": ["shirt-42"],
    "consent": { "version": 1, "at": "2026-09-18T09:00:00Z" }
  }'

Unlike the Try-On API, this call waits and returns the finished image, so allow about a minute:

json

{
  "generationId": "gen_3f9a1c2b7d4e8a10",
  "status": "COMPLETED",
  "imageUrl": "https://example.com/signed-link",
  "garmentPhrase": "blue and black check shirt",
  "durationMs": 45113
}

person must be a base64 data:image/ string. Products must be in your catalogue, with up to 6 in one try-on. A refused photo uses no credit.

Use a session with your own customer ID#

From your server, exchange your secret key for a short-lived token tied to one shopper and one store domain: