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 temas | Tienda «Headless» (de Hydrogen) | |
|---|---|---|
| Escaparate | Tema de Shopify | Tu aplicación de React en Oxygen |
| Cómo se añade la función de prueba de ropa | Instala la aplicación de Shopify, añade el bloque | Una ruta de servidor y un componente |
| Facturación | Plan de Shopify, en tu factura de Shopify | Créditos de la API para desarrolladores, prepagados |
| Guía | Shopify | Esta página |
Cómo funciona
POST /api/try-on (photo + product image URL)
POST /api/v1/generate (X-API-KEY)
200 image/png
200 image/png
- El comprador pulsa en Pruébatelo en la página de un producto y hace o sube una foto.
- El navegador envía la foto y la URL de la imagen del producto a tu ruta de Hydrogen.
- Tu ruta llama a TryOnCloud con tu clave secreta y recibe la imagen finalizada, normalmente en unos 20 segundos.
- 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:
TRYONCLOUD_API_KEY=tk_dev_v1_your_key_herePara 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:
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.
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).
4. Añade el botón a la página del producto
Crea el archivo app/components/TryOnButton.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:
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:
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
- 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. - Prueba varios productos: camisetas, vestidos, saris, conjuntos de kurta y pantalones.
- Prueba con una foto demasiado grande y con un archivo que no sea de imagen, y comprueba los mensajes de error.
- Elimina
?mock=truey 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ón | Crea 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óviles | Enví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ía | Cada respuesta incluye el campo X-Request-Id. Anótalo junto con los errores y facilítanoslo. |
| Solicitudes de privacidad de los clientes | Enví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 vendidos | El 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álogo | Crea 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áfico | 300 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 clientes | Especificación de OpenAPI 3.1 en /api/v1/openapi.json. |
8. Lista de comprobación para la puesta en marcha
TRYONCLOUD_API_KEYes 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=truede la ruta - Se ha añadido
blob:aimgSrc - Las imágenes de los productos proceden de
cdn.shopify.comy 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, yX-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
- Generar una simulación de prueba: todos los campos y respuestas
- Errores y limitaciones
- Tareas asíncronas, lotes y webhooks
- Estado de la API y la especificación OpenAPI
- Datos, privacidad y el acuerdo de tratamiento de datos