# Shopify Hydrogen (headless)

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](/docs/shopify) nostra [app Shopify](/docs/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](/docs/shopify) | Questa pagina |

## Come funziona

```flow
Shopper browser -> Your Hydrogen route: POST /api/try-on (photo + product image URL)
Your Hydrogen route -> TryOnCloud API: POST /api/v1/generate (X-API-KEY)
TryOnCloud API --> Your Hydrogen route: 200 image/png
Your Hydrogen route --> Shopper browser: 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 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](/docs/async). |
| 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](/contact) in modo da poter pianificare la capacità. |
| Monitoraggio | Tasso di successo in tempo reale e velocità su [/status](/status), utilizzo per chiave in **Generations** (ricerca, esportazione in CSV). |
| Generatori di client | Specifiche OpenAPI 3.1 all'indirizzo [/api/v1/openapi.json](/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](/docs/kiosk) 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](/pricing#developer-api). Per volumi elevati o per un progetto pilota che coinvolga più negozi, [contattaci](/contact) per conoscere i prezzi riservati alle aziende.

## Correlati

- [Genera una simulazione di prova](/docs/generate): ogni campo e ogni risposta
- [Errori](/docs/errors) e [limiti](/docs/limits)
- [Operazioni asincrone, elaborazioni in batch e webhook](/docs/async)
- [Stato dell'API](/status) e [specifica OpenAPI](/api/v1/openapi.json)
- [Dati, privacy](/docs/data-privacy) e l'[accordo sul trattamento dei dati](/dpa)
