# Inicio rápido del SDK web

> Añade el elemento de TryYourSize a cualquier página de producto con una etiqueta script o con npm. Claves publicables, eventos y apariencia.

Source: https://docs.tryyoursize.com/es/quickstarts/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](https://docs.tryyoursize.com/es/quickstarts/shopify.md).

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**

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

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

   **npm**

   ```bash
   npm install @tryyoursize/sdk
   ```

   ```ts
   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)**

   ```html
   <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>
   ```

   **JavaScript**

   ```html
   <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>
   ```

   **React**

   ```tsx
   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](https://docs.tryyoursize.com/es/quickstarts/react.md).

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](https://docs.tryyoursize.com/es/get-started/going-live.md).

## 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](https://docs.tryyoursize.com/es/quickstarts/size-guide.md). |

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](https://docs.tryyoursize.com/es/guides/recommendation-event.md). |

## 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](https://docs.tryyoursize.com/es/guides/recommendation-event.md). |
| `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](https://docs.tryyoursize.com/es/guides/server-side-recommendations.md). |
| `tys.experiment()` | Promesa con `{ experimentId, arm, visitorId }`, o `null` si la tienda no tiene ningún [grupo de control A/B](https://docs.tryyoursize.com/es/guides/ab-holdout.md). |

## 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.

```ts
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».

> **Note: 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.