Launch Modes

Every launcher element decides its own launch mode from the attributes on that exact clicked element. The attributes are the same whether the Shopify trigger block emits them from theme editor settings or you write them by hand with the script install. 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: instant is requested (data-hemsy-mode="instant" on the element itself, or on the script tag as a page-wide default) 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-mode`	`"instant"`	Requests Instant mode for this launcher. `"instant"` is the only value with meaning at the launcher level.
`data-hemsy-model`	`"<modelId>"`	Model UUID for Instant mode. Takes effect when instant is requested on the element or the script tag.
`data-hemsy-action`	`"cart"`	Overrides the final CTA (`checkout` or `cart`) for this launcher only. See Checkout vs Cart.

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.

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 on the launcher element:

data-hemsy-mode="instant" to request the instant path. (Putting it on the script tag instead makes instant the default for every launcher with a model.)
data-hemsy-model for the model to generate with. Add data-hemsy-closet for the products to place on that model. If the model is missing, the instant path is skipped.

<a
  href="#"
  class="hemsy-launcher"
  data-hemsy-mode="instant"
  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 per-launcher

Instant only affects the launcher that requests it. Share buttons, ?share= links, and programmatic opens on the same page all work normally alongside instant launchers, with no separate script tags needed. 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.

?closet= always opens a normal Bundle launch rather than instant generation, since no model ID travels in the URL.

For constructing these URLs, see Deep Links.

Get Started

Installation

Configuration

Resolution order

Launcher attributes

Sandbox

Product context (PDP)

Bundle

Flow

Instant

Getting model IDs

Instant is per-launcher

URL auto-open

​Resolution order

​Launcher attributes

​Sandbox

​Product context (PDP)

​Bundle

​Share

​Flow

​Instant

​Getting model IDs

​Instant is per-launcher

​URL auto-open

Resolution order

Launcher attributes

Sandbox

Product context (PDP)

Bundle

Share

Flow

Instant

Getting model IDs

Instant is per-launcher

URL auto-open