Inicio rápido del SDK web

Para tu equipo de desarrollo

Qué hace: Añade un elemento de TryYourSize a nuestras páginas de producto. Quien ya se haya medido ve su talla con nuestras propias etiquetas de talla, y podemos preseleccionarla en el selector de tallas. Solo recibimos tallas, nunca medidas.

Tiempo necesario: Una tarde para la primera página de producto; menos con la etiqueta script.

Qué enviarle: La clave publicable de prueba (pk_test_…) de Studio → Desarrolladores → Claves de API, y la lista de orígenes de nuestros sitios que hay que registrar (Studio → Ajustes → Tiendas → Sitios permitidos).

En Shopify no hay nada que programar: consulta el inicio rápido de Shopify.

1. Consigue tu clave. En Studio → Desarrolladores → Claves de API (Developers → API keys), copia la clave publicable (pk_test_… por ahora). Registra el origen de tu sitio (por ejemplo, https://staging.brand.com) para el modo de prueba. http://localhost funciona en modo de prueba sin registrarlo.

2. Carga TryYourSize.js.

   Etiqueta script

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

   La ruta /v1/ sirve siempre la última versión compatible de la 1.

   npm

   npm install @tryyoursize/sdk

   import { TryYourSize } from "@tryyoursize/sdk";              // incluido en el bundle de tu app
   // o carga la versión del CDN de forma diferida, una sola vez (como loadStripe):
   import { loadTryYourSize } from "@tryyoursize/sdk/loader";
   const tys = await loadTryYourSize("pk_test_…");              // null durante el SSR

3. Añade el elemento donde se elige la talla. product es el ID de producto o SKU, tal como está sincronizado con TryYourSize.

   HTML (sin código)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();             // hereda la fuente y los colores de tu página
   
     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>
     );
   }

   Consulta el inicio rápido de React.

4. Permite nuestros dominios en tu Content Security Policy (si tienes una): script-src https://js.tryyoursize.com (versión del CDN) y frame-src https://embed.tryyoursize.com.

5. Pruébalo. Abre tu página de producto, inicia sesión con un código enviado por correo electrónico (o mídete sin cuenta) y elige una talla. Cuando todo funcione, sigue Pasar a modo real.

Elementos

Elemento	Qué es
"fit"	El elemento integrado: el inicio de sesión y el aviso de que el cuerpo está listo, directamente en tu página. La ventana de medidas solo se abre para medir. Recomendado.
"button"	Un botón compacto «Encontrar mi talla» que abre la ventana de medidas.
"sizeGuide"	Un enlace «Guía de tallas» del tamaño de un enlace, con el logotipo de TryYourSize, para colocarlo junto a tu selector de tallas. Muestra «Tu talla: M» cuando hay una sesión iniciada. Consulta Botón de guía de tallas.

Componentes web sin código: <tys-fit> y <tys-size-guide>, que emiten eventos DOM (tys:size).

API del elemento

Método
mount(selectorOrElement)	Muestra el elemento. Lanza mount_not_found o already_mounted.
on(event, handler) / once / off	Eventos a continuación. Un handler que lanza un error nunca rompe el SDK.
update({ product })	Cambia de producto (por ejemplo, en una página de variante) sin volver a crear el elemento.
open() / close()	Abre o cierra la ventana de medidas desde tu propia interfaz.
getRecommendation()	Promesa con la talla recomendada del cliente para este producto.
unmount() / destroy()	Lo quita de la página; destroy también elimina los handlers.
elements.update({ appearance })	Cambia el estilo en directo (por ejemplo, para tu modo oscuro) sin recargar nada.

Evento	Datos
ready	{ elementType }: visible y conectado.
size	{ product, size, verified }: el cliente ha elegido una talla en nuestra ventana; preselecciona la variante. verified es true cuando la simulación completa la ha confirmado.
open / close	La ventana de medidas se ha abierto o cerrado. Si hay cambios sin guardar, se pregunta antes al cliente.
loaderror	{ error }: no se ha podido acceder a nuestra ventana (red, bloqueo por CSP).
recommendation	{ product, status, size, studioSize, wearableSizes? }: la talla recomendada del cliente con tus etiquetas. Consulta Talla recomendada y preselección.

Métodos del cliente

Método
tys.elements(options?)	Un grupo de elementos (appearance, locale).
tys.recommendation(product)	Promesa con la talla recomendada del cliente para un producto, sin montar nada. Consulta Talla recomendada y preselección.
tys.recommendationHandle()	Promesa con { handle, expiresAt } o null: un identificador sellado que tu servidor envía a POST /v1/recommendations. Consulta Recomendaciones desde el servidor.
tys.experiment()	Promesa con { experimentId, arm, visitorId }, o null si la tienda no tiene ningún grupo de control A/B.

Errores

Todos los errores del SDK son TryYourSizeError con type (integration_error o load_error), un code estable, message y docUrl.

Código	Cuándo
secret_key_in_browser, invalid_key	Se ha pasado una clave incorrecta a TryYourSize().
mount_not_found, already_mounted, element_destroyed	Uso incorrecto del ciclo de vida del elemento.
unknown_element_type, invalid_option	Argumentos de create() no válidos.
window_unreachable	Se emite con loaderror cuando nuestra ventana no se conecta.
script_load_failed	loadTryYourSize() no ha podido cargar el script del CDN.

Seguridad

• En el navegador, usa solo claves publicables. Cada una funciona únicamente en los orígenes que registres.
• Nuestras ventanas son iframes en embed.tryyoursize.com. Los mensajes entre tu página y nuestra ventana pasan por una lista exacta de orígenes permitidos en ambos lados, y se valida cada argumento.
• Las medidas del cliente nunca llegan a tu página ni a tus servidores: solo la talla.

Modo demo (solo claves de prueba)

Para landing pages y demos de ventas, el elemento fit puede mostrar la prueba virtual integrada en la página sobre un cuerpo de muestra con nombre, sin iniciar sesión. Las medidas de cinta de los cuerpos de muestra son valores sintéticos de tablas de medidas, nunca los de una persona real.

const tys = TryYourSize("pk_test_…");                      // una clave real lanza un error
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" });            // otra prenda
demo.update({ demo: { body: "sample-male-178" } });        // otro cuerpo

Cuerpos de muestra: sample-female-158, sample-female-165, sample-female-172, sample-male-172, sample-male-178, sample-male-186. El modo demo solo muestra resultados precalculados y nunca inicia una simulación al ver la página; si un cuerpo y un producto no tienen resultado, se indica «Aún no simulado en este cuerpo».

Versiones

La ruta del CDN fija la versión principal (/v1/): las mejoras te llegan automáticamente y los cambios incompatibles se publican como /v2/. El paquete npm sigue el versionado semántico.