Piattaforme
Shopify Hydrogen (headless)
Shopify "headless" su Hydrogen e Oxygen: un percorso sul server e un pulsante nella pagina del prodotto.
Gli esempi di codice, gli endpoint e i codici di errore sono gli stessi in ogni linguaggio.
Aggiungi la funzione di prova virtuale a un negozio Shopify headless realizzato con Hydrogen e ospitato su Oxygen. Sono sufficienti un percorso server e un componente per la pagina del prodotto, e la chiave API non viene mai trasmessa al browser.
Cosa significa "headless"
Un normale negozio Shopify visualizza le proprie pagine tramite un tema. La nostra app Shopify aggiunge il pulsante "Prova" a quel tema senza bisogno di codice.
Un negozio headless utilizza Shopify per i prodotti, il carrello, il checkout e i pagamenti, ma la vetrina che vedono gli acquirenti è un'app React separata, realizzata dai tuoi sviluppatori. Hydrogen è il framework di Shopify per quell'app, mentre Oxygen è il servizio di hosting di Shopify dedicato ad essa. Poiché non è presente alcun tema, i blocchi dell’app del tema non vengono visualizzati; pertanto, un negozio headless integra la funzione di prova dei capi tramite l’API per sviluppatori.
| Negozio di temi | Negozio Headless (di Hydrogen) | |
|---|---|---|
| Vetrina | Tema Shopify | La tua app React su Oxygen |
| Come viene aggiunta la funzione "Prova indosso" | Installa l'app Shopify, aggiungi il blocco | Un percorso server e un componente |
| Fatturazione | Piano Shopify, sulla fattura Shopify | Crediti API per sviluppatori, prepagati |
| Guida | Shopify | Questa pagina |
Come funziona
POST /api/try-on (photo + product image URL)
POST /api/v1/generate (X-API-KEY)
200 image/png
200 image/png
- L'acquirente tocca Provalo nella pagina di un prodotto e scatta o carica una foto.
- Il browser invia la foto e l'URL dell'immagine del prodotto alla tua route Hydrogen.
- La tua route chiama TryOnCloud utilizzando la tua chiave segreta e riceve l'immagine pronta, solitamente in circa 20 secondi.
- Il cliente si immagina mentre indossa il prodotto. TryOnCloud non salva nulla, a meno che non si attivi la funzione di salvataggio dei risultati.
1. Ottenere una chiave API
Registrati, apri Dashboard > Chiavi API e crea una chiave. La chiave inizia con tk_dev_v1_ e viene visualizzata per intero solo una volta. Il tuo account offre una serie di prove gratuite e la modalità di prova (?mock=true) è sempre gratuita.
2. Salvare la chiave in Oxygen
Nell'area di amministrazione di Shopify, apri Hydrogen > il tuo negozio > Impostazioni negozio > Ambienti e variabili e aggiungi una variabile segreta:
TRYONCLOUD_API_KEY=tk_dev_v1_your_key_herePer lo sviluppo locale, importalo nel file .env con il comando npx shopify hydrogen env pull oppure aggiungilo manualmente al file .env. Quindi aggiungilo al tipo Env nel file env.d.ts in modo che context.env sia tipizzato:
interface Env extends HydrogenEnv {
TRYONCLOUD_API_KEY: string
}3. Aggiungere il percorso del server
Crea il file app/routes/api.try-on.tsx. Hydrogen lo rende disponibile all'indirizzo /api/try-on. La route accetta solo immagini dei prodotti provenienti dal tuo CDN Shopify, in modo che nessuno possa utilizzare la tua chiave per provare immagini a caso.
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 },
})
}In un progetto Hydrogen basato su Remix meno recente, importa invece i tipi da @shopify/remix-oxygen: import type { ActionFunctionArgs } from "@shopify/remix-oxygen" e definisci il tipo dell'azione come ({ request, context }: ActionFunctionArgs).
4. Aggiungi il pulsante alla pagina del prodotto
Crea il file 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>
)
}Quindi visualizzala nella route del prodotto, app/routes/products.$handle.tsx, con l'immagine della variante selezionata, ricorrendo all'immagine principale del prodotto in caso contrario:
const garmentUrl =
product.selectedOrFirstAvailableVariant?.image?.url ?? product.featuredImage?.url
{garmentUrl && <TryOnButton productImageUrl={garmentUrl} />}Assicurati che la tua query relativa al prodotto richieda image { url } per la variante e featuredImage { url } per il prodotto.
5. Inserisci l'immagine risultante nel tuo CSP
Hydrogen applica una Content Security Policy molto rigorosa. Il risultato viene visualizzato tramite un URL blob:, quindi aggiungi blob: a imgSrc nel file 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:"],
})Non è necessario modificare connectSrc: il browser comunica esclusivamente con la tua route /api/try-on.
6. Effettuare un test prima della messa in produzione
- Imposta la route in modalità di test durante la compilazione: usa
https://www.tryoncloud.com/api/v1/generate?mock=true. In questo modo vengono eseguiti tutti i controlli e la foto viene restituita senza modifiche, senza consumare alcun credito. - Prova alcuni capi: top, abiti, sari, completi kurta e pantaloni.
- Prova con una foto troppo grande e con un file che non sia un'immagine, quindi controlla i messaggi di errore.
- Rimuovi
?mock=trueed esegui delle prove di vestibilità reali.
7. Attuarlo su scala commerciale
I cataloghi di grandi dimensioni e i negozi con molti punti vendita richiedono qualcosa di più di un semplice pulsante. Tutte queste funzionalità sono già integrate:
| Necessità | Come |
|---|---|
| Separazione tra fase di preparazione e fase di produzione | Crea una chiave per ogni ambiente nella sezione Chiavi API. Assegna alla chiave di staging un limite di credito mensile e una data di scadenza, in modo che i test non possano mai utilizzare i crediti di produzione. |
| Tentativi di ricollegamento sicuri sulle reti mobili | Invia un Idempotency-Key (il tryOnId sopra indicato). Un nuovo tentativo della stessa prova dopo un'interruzione della connessione viene addebitato una sola volta, e il pulsante rimane disabilitato mentre la prova è in corso, quindi un doppio tocco non può avviare una seconda prova. |
| Assistenza e revisione | Ogni risposta contiene l'X-Request-Id. Registralo insieme agli errori e riportacelo. |
| Richieste relative alla privacy degli acquirenti | Invia customer_id, quindi elimina i dati di quel cliente con DELETE /api/v1/customers/:id. Le foto dei clienti non vengono mai salvate per impostazione predefinita. |
| Prodotti più venduti | L'analisi del capo viene memorizzata nella cache per 30 giorni, quindi le prove ripetute della stessa foto del prodotto sono più veloci di circa 2 secondi. |
| Immagini del catalogo | Crea foto con il modello per numerosi SKU tramite l'POST /api/v1/batches (fino a 500 per batch) e un webhook firmato quando ciascuna foto è pronta. Consulta le sezioni relative a processi asincroni, batch e webhook. |
| Picchi di traffico | 300 richieste al minuto per chiave e 600 per account. Prima di una grande vendita o del lancio di un'iniziativa festiva, avvisateci in modo da poter pianificare la capacità . |
| Monitoraggio | Tasso di successo in tempo reale e velocità su /status, utilizzo per chiave in Generations (ricerca, esportazione in CSV). |
| Generatori di client | Specifiche OpenAPI 3.1 all'indirizzo /api/v1/openapi.json. |
8. Lista di controllo per la messa in produzione
TRYONCLOUD_API_KEYè una variabile segreta nell'ambiente Oxygen di produzione- La chiave non compare né nel codice del browser né nel codice sorgente della pagina
- Rimosso
?mock=truedalla route - Aggiunto
blob:aimgSrc - Le immagini dei prodotti provengono da
cdn.shopify.come mostrano chiaramente il capo - Informativa sulla privacy visualizzata accanto al pulsante (la foto viene utilizzata solo per la prova virtuale e non viene salvata)
- Crediti ricaricati. Inviamo automaticamente un’e-mail al titolare dell’account quando il saldo scende al 10% dell’ultimo acquisto (almeno 20 crediti)
- Una chiave di produzione distinta dalla chiave di staging, ciascuna con il limite di credito mensile desiderato
Idempotency-Keyinviato ad ogni tentativo di prova eX-Request-Idregistrato in caso di errore
Cronologia
Un team di Hydrogen impiega solitamente da 1 a 2 settimane per un progetto pilota: un giorno per inserire la chiave ed effettuare i test in modalità simulata, due o tre giorni per il percorso e il pulsante nella pagina del prodotto, e il resto per il controllo qualità sui prodotti reali e un lancio graduale.
Anche i negozi
Avete anche negozi fisici? Il chiosco in negozio consente di provare i capi su uno schermo o su uno specchio intelligente, anche mentre i clienti tengono un capo davanti alla telecamera. Utilizza lo stesso account.
Prezzi
I negozi "headless" utilizzano crediti API per sviluppatori: prepagati, senza scadenza e in cui le prove di abbigliamento non andate a buon fine non vengono mai addebitate. Consulta i prezzi. Per volumi elevati o per un progetto pilota che coinvolga più negozi, contattaci per conoscere i prezzi riservati alle aziende.