Search docs

Search the TryOnCloud API docs

Plataformas

Shopify Hydrogen (sin interfaz)

Shopify «headless» con Hydrogen y Oxygen: una ruta de servidor y un botón en la página del producto.

Los ejemplos de código, los puntos finales y los códigos de error son los mismos en todos los idiomas.

Añade la función de prueba virtual a una tienda Shopify headless creada con Hydrogen y alojada en Oxygen. Solo se necesita una ruta de servidor y un componente de página de producto, y la clave API nunca llega al navegador.

Qué significa «sin cabeza»

Una tienda normal de Shopify muestra sus páginas mediante un tema. Nuestra aplicación de Shopify añade el botón «Probar» a ese tema sin necesidad de código.

Una tienda headless utiliza Shopify para los productos, el carrito, el proceso de pago y las transacciones, pero la interfaz que ven los compradores es una aplicación independiente de React creada por tus desarrolladores. Hydrogen es el marco de trabajo de Shopify para esa aplicación y Oxygen es el servicio de alojamiento de Shopify para la misma. Al no haber tema, no aparecen los bloques de la aplicación de temas, por lo que una tienda «headless» incorpora la función de «prueba virtual» a través de la API para desarrolladores.

Tienda de temasTienda «Headless» (de Hydrogen)
EscaparateTema de ShopifyTu aplicación de React en Oxygen
Cómo se añade la función de prueba de ropaInstala la aplicación de Shopify, añade el bloqueUna ruta de servidor y un componente
FacturaciónPlan de Shopify, en tu factura de ShopifyCréditos de la API para desarrolladores, prepagados
GuíaShopifyEsta página

Cómo funciona

Shopper browser
Your Hydrogen route

POST /api/try-on (photo + product image URL)

▶

POST /api/v1/generate (X-API-KEY)

◀

200 image/png

◀

200 image/png

◀
  1. El comprador pulsa en Pruébatelo en la página de un producto y hace o sube una foto.
  2. El navegador envía la foto y la URL de la imagen del producto a tu ruta de Hydrogen.
  3. Tu ruta llama a TryOnCloud con tu clave secreta y recibe la imagen finalizada, normalmente en unos 20 segundos.
  4. El comprador se imagina a sí mismo llevando puesto el producto. TryOnCloud no almacena nada a menos que actives el almacenamiento de resultados.

1. Obtener una clave API

Regístrate, abre el Panel de control > Claves API y crea una clave. Empieza por tk_dev_v1_ y solo se muestra completa una vez. Tu cuenta incluye pruebas gratuitas desde el principio, y el modo de prueba (?mock=true) siempre es gratuito.

2. Guarda la clave en Oxygen

En el panel de administración de Shopify, abre Hydrogen > tu tienda > Configuración de la tienda > Entornos y variables y añade una variable secreta:

bash
TRYONCLOUD_API_KEY=tk_dev_v1_your_key_here

Para el desarrollo local, descárgalo en .env con npx shopify hydrogen env pull o añádelo manualmente a .env. A continuación, añádelo al tipo Env en env.d.ts para que context.env tenga un tipo definido:

ts
interface Env extends HydrogenEnv {
  TRYONCLOUD_API_KEY: string
}

3. Añadir la ruta del servidor

Crea el archivo app/routes/api.try-on.tsx. Hydrogen lo sirve en /api/try-on. La ruta solo acepta imágenes de productos procedentes de tu propio CDN de Shopify, por lo que nadie puede utilizar tu clave para probarse imágenes aleatorias.

ts
import type { Route } from "./+types/api.try-on"

const MAX_PHOTO_BYTES = 15 * 1024 * 1024

export async function action({ request, context }: Route.ActionArgs) {
  if (request.method !== "POST") return new Response("Method not allowed", { status: 405 })

  const incoming = await request.formData()
  const person = incoming.get("person")
  const garmentUrl = incoming.get("garmentUrl")
  // One id per try-on, made in the browser. A retry with the same id is never charged twice.
  const tryOnId = incoming.get("tryOnId")

  if (!(person instanceof Blob) || person.size === 0 || person.size > MAX_PHOTO_BYTES) {
    return Response.json({ error: "Please add a photo under 15MB." }, { status: 400 })
  }
  // Only your own product images: blocks anyone using this route as a free try-on service.
  if (typeof garmentUrl !== "string" || !garmentUrl.startsWith("https://cdn.shopify.com/")) {
    return Response.json({ error: "Invalid product image." }, { status: 400 })
  }

  const form = new FormData()
  form.append("person_image", person, "person.jpg")
  form.append("garment_url", garmentUrl)
  // Optional: your own shopper id (for example a hash of the Customer Account id),
  // so you can find this shopper's try-ons and erase them on request.
  // form.append("customer_id", shopperId)

  const headers: Record<string, string> = { "X-API-KEY": context.env.TRYONCLOUD_API_KEY }
  if (typeof tryOnId === "string" && /^[\w-]{8,64}$/.test(tryOnId)) headers["Idempotency-Key"] = tryOnId

  const res = await fetch("https://www.tryoncloud.com/api/v1/generate", {
    method: "POST",
    headers,
    body: form,
    signal: AbortSignal.timeout(120_000),
  })
  const requestId = res.headers.get("X-Request-Id") ?? ""

  if (!res.ok) {
    const { error, code } = await res.json()
    console.error("try-on failed", code, requestId) // quote requestId to TryOnCloud support
    return Response.json({ error, code }, { status: res.status })
  }
  return new Response(res.body, {
    headers: { "Content-Type": "image/png", "Cache-Control": "no-store", "X-Request-Id": requestId },
  })
}

En un proyecto Hydrogen más antiguo basado en Remix, importa los tipos desde @shopify/remix-oxygen: import type { ActionFunctionArgs } from "@shopify/remix-oxygen", y define el tipo de la acción como ({ request, context }: ActionFunctionArgs).

Nota: Una prueba tarda unos 20 segundos. Mantén la solicitud abierta y no añadas un tiempo de espera más corto al principio de esta ruta. Las pruebas fallidas se reembolsan automáticamente.

4. Añade el botón a la página del producto

Crea el archivo app/components/TryOnButton.tsx:

tsx
import { useState } from "react"

export function TryOnButton({ productImageUrl }: { productImageUrl: string }) {
  const [result, setResult] = useState<string | null>(null)
  const [busy, setBusy] = useState(false)
  const [error, setError] = useState<string | null>(null)

  async function onFile(file: File) {
    setBusy(true)
    setError(null)
    const form = new FormData()
    form.append("person", file)
    form.append("garmentUrl", productImageUrl)
    form.append("tryOnId", crypto.randomUUID()) // reuse the same id if you add a "Retry" button
    try {
      const res = await fetch("/api/try-on", { method: "POST", body: form })
      if (!res.ok) throw new Error((await res.json()).error ?? "Try-on failed")
      setResult(URL.createObjectURL(await res.blob()))
    } catch (e) {
      setError(e instanceof Error ? e.message : "Try-on failed")
    } finally {
      setBusy(false)
    }
  }

  return (
    <div>
      <label>
        {busy ? "Creating your look..." : "Try it on"}
        <input
          type="file"
          accept="image/*"
          capture="user"
          hidden
          disabled={busy}
          onChange={(e) => e.target.files?.[0] && onFile(e.target.files[0])}
        />
      </label>
      <p>Your photo is used only to create this image and is not stored.</p>
      {error && <p role="alert">{error}</p>}
      {result && <img src={result} alt="You wearing this product" />}
    </div>
  )
}

A continuación, muéstrala en la ruta del producto, app/routes/products.$handle.tsx, con la imagen de la variante seleccionada; si no está disponible, utiliza la imagen principal del producto:

tsx
const garmentUrl =
  product.selectedOrFirstAvailableVariant?.image?.url ?? product.featuredImage?.url

{garmentUrl && <TryOnButton productImageUrl={garmentUrl} />}

Asegúrate de que tu consulta sobre el producto solicite image { url } en la variante y featuredImage { url } en el producto.

5. Permite la imagen del resultado en tu CSP

Hydrogen envía una política de seguridad de contenido (CSP) estricta. El resultado se muestra a partir de una URL blob:, así que añade blob: a imgSrc en app/entry.server.tsx:

ts
const { nonce, header, NonceProvider } = createContentSecurityPolicy({
  shop: { checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN, storeDomain: context.env.PUBLIC_STORE_DOMAIN },
  imgSrc: ["'self'", "https://cdn.shopify.com", "data:", "blob:"],
})

No es necesario modificar connectSrc: el navegador solo se comunica con tu propia ruta /api/try-on.

6. Realiza pruebas antes de ponerlo en marcha

  1. Configura la ruta en modo de prueba mientras la creas: utiliza https://www.tryoncloud.com/api/v1/generate?mock=true. Se ejecutan todas las comprobaciones y se devuelve la foto sin modificaciones, sin que se consuma ningún crédito.
  2. Prueba varios productos: camisetas, vestidos, saris, conjuntos de kurta y pantalones.
  3. Prueba con una foto demasiado grande y con un archivo que no sea de imagen, y comprueba los mensajes de error.
  4. Elimina ?mock=true y realiza pruebas reales.

7. Ponerlo en marcha a escala comercial

Los catálogos extensos y las tiendas numerosas necesitan algo más que un botón. Todo esto ya está integrado:

Necesidad¿Cómo?
Separar la puesta en escena y la producciónCrea una clave por entorno en Claves de API. Asigna a la clave de entorno de pruebas un límite de crédito mensual y una fecha de caducidad, de modo que las pruebas nunca puedan gastar créditos de producción.
Reintentos seguros en redes móvilesEnvía una Idempotency-Key (el tryOnId mencionado anteriormente). Un nuevo intento de la misma prueba tras una pérdida de conexión se cobra una sola vez, y el botón queda desactivado mientras se está realizando una prueba, por lo que un doble toque no puede iniciar una segunda prueba.
Asistencia y auditoríaCada respuesta incluye el campo X-Request-Id. Anótalo junto con los errores y facilítanoslo.
Solicitudes de privacidad de los clientesEnvía customer_id y, a continuación, borra los datos de ese cliente con DELETE /api/v1/customers/:id. Las fotos de los clientes nunca se almacenan de forma predeterminada.
Productos más vendidosEl análisis de la prenda se almacena en caché durante 30 días, por lo que las pruebas repetidas de la misma foto del producto son unos 2 segundos más rápidas.
Imágenes del catálogoCrea fotos con modelo para numerosas referencias (SKU) mediante POST /api/v1/batches (hasta 500 por lote) y un webhook firmado cuando cada una esté lista. Consulta la sección sobre tareas asíncronas, lotes y webhooks.
Horas punta de tráfico300 solicitudes por minuto por clave y 600 por cuenta. Antes de una gran oferta o un lanzamiento festivo, avísanos para que podamos planificar la capacidad.
SeguimientoÍndice de éxito y velocidad en tiempo real en /status; uso por clave en Generations (búsqueda, exportación a CSV).
Generadores de clientesEspecificación de OpenAPI 3.1 en /api/v1/openapi.json.

8. Lista de comprobación para la puesta en marcha

  • TRYONCLOUD_API_KEY es una variable secreta en el entorno de producción de Oxygen
  • La clave no aparece en ninguna parte del código del navegador ni en el código fuente de la página.
  • Se ha eliminado ?mock=true de la ruta
  • Se ha añadido blob: a imgSrc
  • Las imágenes de los productos proceden de cdn.shopify.com y muestran la prenda con claridad
  • La línea de privacidad que aparece junto al botón (la foto se utiliza únicamente para la prueba y no se guarda)
  • Créditos recargados. Enviamos automáticamente un correo electrónico al titular de la cuenta cuando el saldo desciende al 10 % del importe de la última compra (un mínimo de 20 créditos).
  • Una clave de producción independiente de la clave de prueba, cada una con el límite de crédito mensual que desees
  • Idempotency-Key, enviado en cada intento de prueba, y X-Request-Id, registrado en caso de error

Cronología

Un equipo de Hydrogen suele necesitar entre una y dos semanas para una prueba piloto: un día para añadir la clave y realizar pruebas en modo simulado, dos o tres días para la ruta y el botón de la página del producto, y el resto para el control de calidad con productos reales y un lanzamiento por fases.

Las tiendas también

¿También tenéis tiendas físicas? El quiosco de la tienda permite probarse la ropa en una pantalla o en un espejo inteligente, incluso cuando los clientes se acercan con una prenda a la cámara. Se utiliza la misma cuenta.

Precios

Las tiendas «Headless» utilizan créditos de la API para desarrolladores: son de prepago, no caducan nunca y no se cobra por las pruebas fallidas. Consulta las tarifas. Para grandes volúmenes o un proyecto piloto en varias tiendas, ponte en contacto con nosotros para conocer las tarifas para empresas.

Relacionado