Web SDK quickstart

For your developer

What it does: Adds a TryYourSize element to our product pages. Shoppers who have measured see their size in our own size labels; we can preselect it in the size picker. We receive sizes only, never measurements.

Time needed: An afternoon for a first product page; less with the script tag.

What to send them: The test publishable key (pk_test_…) from Studio → Developers → API keys, and the list of our site origins to register (Studio → Settings → Stores → Allowed sites).

On Shopify there is nothing to code: see the Shopify quickstart.

1. Get your key. In Studio → Developers → API keys, copy the publishable key (pk_test_… for now). Register the origin of your site (for example https://staging.brand.com) for test mode. http://localhost works in test mode without registering.

2. Load TryYourSize.js.

   Script tag

   <script src="https://js.tryyoursize.com/v1/tys.js"></script>

   The /v1/ path always serves the latest compatible version 1.

   npm

   npm install @tryyoursize/sdk

   import { TryYourSize } from "@tryyoursize/sdk";              // bundled into your app
   // or load the CDN build lazily, once (like loadStripe):
   import { loadTryYourSize } from "@tryyoursize/sdk/loader";
   const tys = await loadTryYourSize("pk_test_…");              // null during SSR

3. Add the element where shoppers choose a size. product is your product ID or SKU, as synced to TryYourSize.

   HTML (no code)JavaScriptReact

   <script src="https://js.tryyoursize.com/v1/tys.js"></script>
   
   <tys-fit publishable-key="pk_test_…" product="STRAIGHT-JEANS"></tys-fit>
   
   <script>
     document.querySelector("tys-fit")
       .addEventListener("tys:size", (e) => selectVariant(e.detail.size));
   </script>

   <div id="tys-fit"></div>
   <script>
     const tys = TryYourSize("pk_test_…");
     const elements = tys.elements();             // inherits your page's font and colours
   
     const fit = elements.create("fit", { product: "STRAIGHT-JEANS" });
     fit.mount("#tys-fit");
     fit.on("size", ({ size, verified }) => selectVariant(size));
   </script>

   import { loadTryYourSize } from "@tryyoursize/sdk/loader";
   import { TryYourSizeProvider, FitElement } from "@tryyoursize/react";
   
   const tysPromise = loadTryYourSize("pk_test_…");
   
   export function ProductPage() {
     return (
       <TryYourSizeProvider client={tysPromise}>
         <FitElement product="STRAIGHT-JEANS" onSize={({ size }) => selectVariant(size)} />
       </TryYourSizeProvider>
     );
   }

   See the React quickstart.

4. Allow our domains in your Content Security Policy (if you have one): script-src https://js.tryyoursize.com (CDN build) and frame-src https://embed.tryyoursize.com.

5. Try it. Open your product page, sign in with an email code (or measure without an account), and pick a size. When everything works, follow Going live.

Elements

Element	What it is
"fit"	The inline element: sign-in and “your body is ready” right in your page. The measuring window opens only to measure. Recommended.
"button"	A compact “Find my size” button that opens the measuring window.
"sizeGuide"	A link-sized “Size guide” with the TryYourSize mark, for the spot next to your size picker. Shows “Your size: M” when the shopper is connected. See Size guide button.

No-code web components: <tys-fit> and <tys-size-guide>, which emit DOM events (tys:size).

Element API

Method
mount(selectorOrElement)	Shows the element. Throws mount_not_found or already_mounted.
on(event, handler) / once / off	Events below. A handler that throws never breaks the SDK.
update({ product })	Switch product (for example on a variant page) without recreating the element.
open() / close()	Open or close the measuring window from your own UI.
getRecommendation()	Promise of the shopper’s recommended size for this product.
unmount() / destroy()	Remove from the page; destroy also drops handlers.
elements.update({ appearance })	Live restyle (for example your dark mode), without reloading anything.

Event	Payload
ready	{ elementType }: shown and connected.
size	{ product, size, verified }: the shopper chose a size in our window; preselect the variant. verified is true when the full simulation confirmed it.
open / close	The measuring window opened or closed. Closing with unsaved changes asks the shopper first.
loaderror	{ error }: our window could not be reached (network, blocked by CSP).
recommendation	{ product, status, size, studioSize, wearableSizes? }: the shopper’s recommended size in your labels. See Recommended size and preselection.

Client methods

Method
tys.elements(options?)	An elements group (appearance, locale).
tys.recommendation(product)	Promise of the shopper’s recommended size for a product, without mounting anything. See Recommended size and preselection.
tys.recommendationHandle()	Promise of { handle, expiresAt } or null: a sealed handle your server sends to POST /v1/recommendations. See Server-side recommendations.
tys.experiment()	Promise of { experimentId, arm, visitorId } or null when the store runs no A/B holdout.

Errors

All SDK errors are TryYourSizeError with type (integration_error or load_error), a stable code, message and docUrl.

Code	When
secret_key_in_browser, invalid_key	Wrong key passed to TryYourSize().
mount_not_found, already_mounted, element_destroyed	Element lifecycle misuse.
unknown_element_type, invalid_option	Bad create() arguments.
window_unreachable	Emitted with loaderror when our window does not connect.
script_load_failed	loadTryYourSize() could not load the CDN script.

Security

• Use publishable keys only in the browser. Each works only on the origins you register.
• Our windows are iframes on embed.tryyoursize.com. Messages between your page and our window go through an exact origin allow-list on both sides, and every argument is validated.
• The shopper’s measurements never reach your page or your servers: only the size does.

Demo mode (test keys only)

For landing pages and sales demos, the fit element can show the try-on inline on a named sample body, with no sign-in. Sample body tape values are synthetic size-chart values, never a real person’s.

const tys = TryYourSize("pk_test_…");                      // a live key throws
const demo = tys.elements().create("fit", {
  product: "CREW-TSHIRT",
  demo: { body: "sample-female-165", height: 640 },
});
demo.mount("#demo");
demo.update({ product: "SLIM-STRETCH-JEANS" });            // another garment
demo.update({ demo: { body: "sample-male-178" } });        // another body

Sample bodies: sample-female-158, sample-female-165, sample-female-172, sample-male-172, sample-male-178, sample-male-186. Demo mode shows precomputed results only and never starts a simulation on a page view; a body and product without a result says “Not simulated on this body yet”.

Versioning

The CDN path pins the major version (/v1/): improvements reach you automatically, and breaking changes ship as /v2/. The npm package follows semantic versioning.