Launch Modes - Hemsy | API Documentation

Every launcher element decides its own launch mode from the attributes on that exact clicked element. This page covers each mode and the order they’re resolved in.

Resolution order

When a launcher is clicked, Hemsy picks the launch mode by checking, in order:

Instant: the script tag has data-hemsy-mode="instant" and the element has data-hemsy-model.
Share: the element has data-hemsy-share.
Product: the element has data-hemsy-auto-product-context="true".
Bundle: the element has data-hemsy-closet.
Sandbox: none of the above; opens the full experience blank.

data-hemsy-flow starts a guided flow when the launch has an empty look (Sandbox, or a flow-only launcher). Bundle (data-hemsy-closet) and Share launches skip the guided flow: closet bypass jumps straight to try-on after a photo is chosen, and share opens the shared-look viewer. data-hemsy-action (checkout vs cart) is independent of launch mode. It only changes what the final CTA does. See Checkout vs Cart.

Launcher attributes

Attribute	Example	Description
`data-hemsy-share`	`"FreyjHz4"`	Opens a previously shared look by its short ID.
`data-hemsy-auto-product-context`	`"true"`	Auto-builds a product payload from the current PDP variant. Falls back to Sandbox if no variant is detected.
`data-hemsy-closet`	`"eyJwcm9k..."`	Explicit URL-safe base64 product payload. Use for Bundle mode.
`data-hemsy-flow`	`"<flowId>"`	Starts a guided flow on an empty-look launch. Ignored for Bundle and Share. Must be on the clicked element.
`data-hemsy-model`	`"<modelId>"`	Model UUID for Instant mode. Only takes effect when the script has `data-hemsy-mode="instant"`.

Sandbox

The default. No launcher attributes needed. The shopper starts blank and builds a look from your full catalog.

<a class="hemsy-launcher" href="#">Design a look</a>

Product context (PDP)

Launch with the product the shopper is currently viewing. Hemsy reads the selected variant from the page (the add-to-cart form or a ?variant= URL parameter) and pre-loads it.

<button class="hemsy-launcher" data-hemsy-auto-product-context="true">
  Try with this product
</button>

If no variant can be detected, the launcher falls back to Sandbox mode.

Bundle

Pre-load one or more specific products, curated looks, bundles, or campaign selections, with an explicit payload on data-hemsy-closet.

<button class="hemsy-launcher" data-hemsy-closet="YOUR_URLSAFE_BASE64_PAYLOAD">
  Try on Bed Bundle
</button>

The payload is a URL-safe base64 encoding of a JSON object listing products:

{
  "products": [
    {
      "variantId": 1234567890,
      "attributes": [{ "key": "_bundleTitle", "value": "Starter Bundle" }]
    }
  ]
}

The attribute is named data-hemsy-closet for historical reasons. A “closet” payload is how Bundle mode describes its products. The same payload format powers ?closet= deep links.

For the full payload schema, bundle attribute keys (_bundleId, _uniqueId, and friends), encoding helpers, and a validation checklist, see Deep Links. Always wrap data-hemsy-closet values in quotes. Open a previously shared look by its short ID. Useful for marketing campaigns, emails, or featuring shopper-created looks on your storefront.

<button class="hemsy-launcher" data-hemsy-share="FreyjHz4">
  View Shared Look
</button>

Share IDs are generated by Hemsy’s in-app Share feature; you don’t construct them yourself.

Share launchers do not work when the embed script has data-hemsy-mode="instant": the share parameter is dropped for the whole embed instance, including ?share= links and programmatic opens. Keep share buttons on pages using the default script mode.

Flow

Launch a guided, step-by-step flow with an empty look:

<button class="hemsy-launcher" data-hemsy-flow="YOUR_FLOW_ID">
  Build a bed
</button>

Copy flow IDs from the dashboard. The shopper walks the steps, then can exit into free browse. Do not combine data-hemsy-flow with Bundle or Share launchers: those paths skip the guided flow.

Instant

Instant mode skips model selection and immediately generates a try-on image with a specific model and product payload. The shopper clicks, sees the generation loading state, and lands on the result. Instant requires both pieces:

data-hemsy-mode="instant" on the script tag (page-wide).
data-hemsy-model and data-hemsy-closet on the launcher element. If either is missing, the instant path is skipped.

<script
  src="https://hemsy.ai/hemsy-embed.js"
  data-hemsy-subdomain="your-store-subdomain"
  data-hemsy-selector=".hemsy-launcher"
  data-hemsy-mode="instant"
  defer
></script>

<a
  href="#"
  class="hemsy-launcher"
  data-hemsy-model="YOUR_MODEL_ID"
  data-hemsy-closet="YOUR_URLSAFE_BASE64_PAYLOAD"
>
  See it on a model
</a>

Getting model IDs

Model IDs are UUIDs assigned to each image in your store’s model library:

Go to your store’s Models page in the Hemsy dashboard.
Hover over any model image.
Click the copy icon in the bottom-left corner.

Instant is page-wide

data-hemsy-mode="instant" changes how the whole embed instance builds its launch URLs: only instant parameters are forwarded, and share parameters are stripped.

On a page with an instant script tag: share launchers, ?share= auto-open links, and HemsyEmbed.open("share", ...) all silently fail. If you need both instant and share launchers on the same page, load separate script tags.

Instant combines normally with data-hemsy-action="cart" if your storefront owns cart state. See Checkout vs Cart.

URL auto-open

The embed script watches the page URL for ?share= and ?closet= parameters and opens the modal automatically on page load:

https://your-store.com/?share=FreyjHz4
https://your-store.com/?closet=eyJwcm9kdWN0cy...

This powers share links (recipients see the look immediately) and marketing campaigns (pre-load products from ads or emails). The parameter is removed from the URL after opening so a refresh doesn’t re-trigger it. For SPAs, the script also intercepts history.pushState to catch client-side navigations.

Under an instant script tag, ?share= auto-open does not work (share is stripped), and ?closet= opens a normal Bundle launch rather than instant generation, since no model ID is present in the URL.

For constructing these URLs, see Deep Links.

​Resolution order

​Launcher attributes

​Sandbox

​Product context (PDP)

​Bundle

​Share

​Flow

​Instant

​Getting model IDs

​Instant is page-wide

​URL auto-open

Resolution order

Launcher attributes

Sandbox

Product context (PDP)

Bundle

Share

Flow

Instant

Getting model IDs

Instant is page-wide

URL auto-open