Search docs

Search the TryOnCloud API docs

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 temiNegozio Headless (di Hydrogen)
VetrinaTema ShopifyLa tua app React su Oxygen
Come viene aggiunta la funzione "Prova indosso"Installa l'app Shopify, aggiungi il bloccoUn percorso server e un componente
FatturazionePiano Shopify, sulla fattura ShopifyCrediti API per sviluppatori, prepagati
GuidaShopifyQuesta pagina

Come funziona

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. L'acquirente tocca Provalo nella pagina di un prodotto e scatta o carica una foto.
  2. Il browser invia la foto e l'URL dell'immagine del prodotto alla tua route Hydrogen.
  3. La tua route chiama TryOnCloud utilizzando la tua chiave segreta e riceve l'immagine pronta, solitamente in circa 20 secondi.
  4. 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:

bash
TRYONCLOUD_API_KEY=tk_dev_v1_your_key_here

Per 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:

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

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 },
  })
}

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

Nota: una prova richiede circa 20 secondi. Mantieni aperta la richiesta e non impostare un timeout più breve per questa route. Le prove non andate a buon fine vengono rimborsate automaticamente.

4. Aggiungi il pulsante alla pagina del prodotto

Crea il file 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>
  )
}

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:

tsx
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:

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:"],
})

Non è necessario modificare connectSrc: il browser comunica esclusivamente con la tua route /api/try-on.

6. Effettuare un test prima della messa in produzione

  1. 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.
  2. Prova alcuni capi: top, abiti, sari, completi kurta e pantaloni.
  3. Prova con una foto troppo grande e con un file che non sia un'immagine, quindi controlla i messaggi di errore.
  4. Rimuovi ?mock=true ed 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 produzioneCrea 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 mobiliInvia 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 revisioneOgni risposta contiene l'X-Request-Id. Registralo insieme agli errori e riportacelo.
Richieste relative alla privacy degli acquirentiInvia 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ù vendutiL'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 catalogoCrea 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 traffico300 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à.
MonitoraggioTasso di successo in tempo reale e velocità su /status, utilizzo per chiave in Generations (ricerca, esportazione in CSV).
Generatori di clientSpecifiche 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=true dalla route
  • Aggiunto blob: a imgSrc
  • Le immagini dei prodotti provengono da cdn.shopify.com e 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-Key inviato ad ogni tentativo di prova e X-Request-Id registrato 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.

Correlati