# Shopify Hydrogen (Headless)

Fügen Sie eine virtuelle Anprobe zu einem **Headless-Shopify-Shop** hinzu, der mit Hydrogen erstellt und auf Oxygen gehostet wird. Dazu sind lediglich eine Server-Route und eine Komponente für die Produktseite erforderlich, und der API-Schlüssel gelangt zu keinem Zeitpunkt in den Browser.

## Was „headless“ bedeutet

Ein normaler Shopify-Shop stellt seine Seiten mithilfe eines **Themes** dar. Unsere [Shopify-App](/docs/shopify) fügt diesem Theme die „Anprobieren“-Schaltfläche hinzu, ganz ohne Programmieraufwand.

Ein **Headless-Shop** nutzt Shopify für Produkte, Warenkorb, Kasse und Zahlungen, doch die Shop-Oberfläche, die die Kunden sehen, ist eine separate **React-App, die** von Ihren Entwicklern erstellt wurde. Hydrogen ist das Framework von Shopify für diese App und Oxygen ist das Hosting von Shopify dafür. Da es kein Theme gibt, werden keine Theme-App-Blöcke angezeigt; daher wird in einem Headless-Shop die Anprobe stattdessen über die **Entwickler-API** integriert.

|  | Themen-Shop | Headless (Hydrogen)-Shop |
|---|---|---|
| Ladenfront | Shopify-Theme | Ihre React-App auf Oxygen |
| So wird die Anprobe hinzugefügt | Installieren Sie die Shopify-App und fügen Sie den Block hinzu | Eine Serverroute und eine Komponente |
| Rechnungsstellung | Shopify-Tarif, auf Ihrer Shopify-Rechnung | Entwickler-API-Guthaben, im Voraus bezahlt |
| Leitfaden | [Shopify](/docs/shopify) | Diese Seite |

## So funktioniert es

```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. Der Kunde tippt auf einer Produktseite auf **Anprobieren** und macht oder lädt ein Foto hoch.
2. Der Browser sendet das Foto und die Bild-URL des Produkts an **Ihre** Hydrogen-Route.
3. Ihre Route ruft TryOnCloud mit Ihrem geheimen Schlüssel auf und erhält das fertige Bild zurück, in der Regel innerhalb von etwa 20 Sekunden.
4. Der Kunde stellt sich vor, wie er das Produkt trägt. TryOnCloud speichert keine Daten, es sei denn, Sie aktivieren die Speicherung der Ergebnisse.

## 1. Einen API-Schlüssel anfordern

Registrieren Sie sich, öffnen Sie **Dashboard > API-Schlüssel** und erstellen Sie einen Schlüssel. Dieser beginnt mit `tk_dev_v1_` und wird nur einmal vollständig angezeigt. Ihr Konto beginnt mit kostenlosen Testzugängen, und der Testmodus (`?mock=true`) ist immer kostenlos.

## 2. Speichern Sie den Schlüssel in Oxygen

Öffnen Sie im Shopify-Adminbereich **Hydrogen > Ihr Shop > Shop-Einstellungen > Umgebungen und Variablen** und fügen Sie eine **geheime** Variable hinzu:

```bash
TRYONCLOUD_API_KEY=tk_dev_v1_your_key_here
```

Für die lokale Entwicklung können Sie die Daten mit `npx shopify hydrogen env pull` in die Datei `.env` einlesen oder sie manuell in `.env` einfügen. Fügen Sie sie anschließend dem Typ `Env` in `env.d.ts` hinzu, damit `context.env` typisiert ist:

```ts
interface Env extends HydrogenEnv {
  TRYONCLOUD_API_KEY: string
}
```

## 3. Fügen Sie die Serverroute hinzu

Erstellen Sie die Datei `app/routes/api.try-on.tsx`. Hydrogen stellt sie unter `/api/try-on` bereit. Die Route akzeptiert ausschließlich Produktbilder aus Ihrem eigenen Shopify-CDN, sodass niemand Ihren Schlüssel verwenden kann, um beliebige Bilder anzuprobieren.

```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 einem älteren, auf Remix basierenden Hydrogen-Projekt sollten Sie die Typen stattdessen aus `@shopify/remix-oxygen` importieren: `import type { ActionFunctionArgs } from "@shopify/remix-oxygen"` und die Aktion als `({ request, context }: ActionFunctionArgs)` typisieren.

> **Hinweis:** Ein Anprobieren dauert etwa 20 Sekunden. Halten Sie die Anfrage offen und fügen Sie vor dieser Route kein kürzeres Timeout ein. Fehlgeschlagene Anproben werden automatisch erstattet.

## 4. Fügen Sie die Schaltfläche zur Produktseite hinzu

Erstellen Sie die Datei `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>
  )
}
```

Rendern Sie es anschließend in Ihrer Produkt-Route (`app/routes/products.$handle.tsx`) mit dem Bild der ausgewählten Variante, wobei Sie auf das Hauptbild des Produkts zurückgreifen, falls kein Bild vorhanden ist:

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

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

Stellen Sie sicher, dass Ihre Produktabfrage `image { url }` für die Variante und `featuredImage { url }` für das Produkt abfragt.

## 5. Fügen Sie das Ergebnisbild in Ihr CSP ein

Hydrogen übermittelt eine strenge Content Security Policy. Das Ergebnis wird über eine `blob:`-URL angezeigt. Fügen Sie daher `blob:` zu `imgSrc` in `app/entry.server.tsx` hinzu:

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

Es ist keine Änderung an `connectSrc` erforderlich: Der Browser kommuniziert ausschließlich mit Ihrer eigenen Route `/api/try-on`.

## 6. Vor der Inbetriebnahme testen

1. Stellen Sie die Route während des Erstellvorgangs auf den Testmodus ein: Verwenden Sie `https://www.tryoncloud.com/api/v1/generate?mock=true`. Dabei werden alle Prüfungen durchgeführt, und das Foto wird unverändert zurückgegeben, ohne dass Guthaben verbraucht wird.
2. Probieren Sie ein paar Produkte aus: Oberteile, Kleider, Saris, Kurta-Sets und Unterteile.
3. Probieren Sie es mit einem zu großen Foto und einer Datei, die kein Bild ist, und sehen Sie sich die Fehlermeldungen an.
4. Entfernen Sie `?mock=true` und führen Sie echte Anproben durch.

## 7. Im kommerziellen Maßstab betreiben

Umfangreiche Kataloge und zahlreiche Geschäfte erfordern etwas mehr als nur eine Schaltfläche. All dies ist bereits integriert:

| Bedarf | Wie |
|---|---|
| Trennung von Entwicklung und Produktion | Erstellen Sie unter **API-Schlüssel** einen Schlüssel pro Umgebung. Legen Sie für den Staging-Schlüssel ein **monatliches Guthabenlimit** und ein **Ablaufdatum** fest, damit bei Tests niemals Produktionsguthaben verbraucht wird. |
| Sichere Wiederholungsversuche in Mobilfunknetzen | Senden Sie einen `Idempotency-Key` (das oben genannte `tryOnId`). Ein erneuter Versuch desselben Anprobiervorgangs nach einem Verbindungsabbruch wird einmalig berechnet, und die Schaltfläche ist während eines laufenden Anprobiervorgangs deaktiviert, sodass durch ein doppeltes Antippen kein zweiter Vorgang gestartet werden kann. |
| Unterstützung und Prüfung | Jede Antwort enthält einen `X-Request-Id`-Header. Protokollieren Sie diesen zusammen mit Ihren Fehlermeldungen und geben Sie ihn uns an. |
| Anfragen von Kunden zum Datenschutz | Senden Sie `customer_id` und löschen Sie anschließend die Daten dieses Kunden mit `DELETE /api/v1/customers/:id`. Kundenfotos werden standardmäßig niemals gespeichert. |
| Beliebte Produkte | Die Kleideranalyse wird 30 Tage lang zwischengespeichert, sodass wiederholte Anproben desselben Produktfotos etwa 2 Sekunden schneller erfolgen. |
| Katalogbilder | Erstellen Sie mit `POST /api/v1/batches` (bis zu 500 pro Stapel) Fotos mit Models für zahlreiche Artikel (SKUs) und erhalten Sie einen signierten Webhook, sobald jedes Foto fertig ist. Weitere Informationen finden Sie unter [Asynchrone Aufträge, Stapel und Webhooks](/docs/async). |
| Verkehrsspitzen | 300 Anfragen pro Minute pro Schlüssel und 600 pro Konto. Bitte [informieren Sie uns](/contact) vor einem großen Verkauf oder einer festlichen Produkteinführung, damit wir die Kapazitäten entsprechend planen können. |
| Überwachung | Aktuelle Erfolgsquote und Geschwindigkeit unter [/status](/status), Nutzung pro Schlüssel in **Generations** (Suche, CSV-Export). |
| Client-Generatoren | OpenAPI 3.1-Spezifikation unter [/api/v1/openapi.json](/api/v1/openapi.json). |

## 8. Checkliste für die Inbetriebnahme

- `TRYONCLOUD_API_KEY` ist eine **geheime** Variable in der Oxygen-Produktionsumgebung
- Der Schlüssel taucht weder im Browser-Code noch im Quellcode der Seite auf.
- `?mock=true` wurde aus der Route entfernt
- `blob:` wurde zu `imgSrc` hinzugefügt
- Die Produktbilder stammen von `cdn.shopify.com` und zeigen das Kleidungsstück deutlich
- Die Datenschutzhinweise werden neben der Schaltfläche angezeigt (das Foto dient nur zur Ansicht und wird nicht gespeichert)
- Guthaben aufgefüllt. Wir senden dem Kontoinhaber automatisch eine E-Mail, sobald das Guthaben auf 10 % des letzten Kaufbetrags (mindestens 20 Credits) gesunken ist.
- Ein Produktionsschlüssel, der vom Staging-Schlüssel getrennt ist, wobei jeder über das von Ihnen gewünschte monatliche Kreditlimit verfügt
- Bei jedem Anprobieren wird ein `Idempotency-Key` gesendet, und bei Fehlern wird ein `X-Request-Id` protokolliert

## Zeitleiste

Ein Hydrogen-Team benötigt in der Regel **1 bis 2 Wochen** für ein Pilotprojekt: einen Tag für die Eingabe des Schlüssels und den Test im Simulationsmodus, zwei oder drei Tage für die Route und die Schaltfläche auf der Produktseite sowie den Rest für die Qualitätssicherung an echten Produkten und eine schrittweise Einführung.

## Auch Geschäfte

Gibt es auch stationäre Geschäfte? Der [Kiosk im Geschäft](/docs/kiosk) ermöglicht das Anprobieren auf einem Bildschirm oder einem Smart-Spiegel, wobei die Kunden ein Kleidungsstück vor die Kamera halten können. Dabei wird dasselbe Konto verwendet.

## Preise

Headless-Shops nutzen **Developer-API-Guthaben**: Diese sind im Voraus bezahlt, verfallen nie, und eine fehlgeschlagene Anprobe wird niemals in Rechnung gestellt. Siehe [Preisübersicht](/pricing#developer-api). Bei hohem Volumen oder einem Pilotprojekt über mehrere Shops hinweg [kontaktieren Sie uns bitte](/contact), um unsere Unternehmenspreise zu erfahren.

## Verwandte Themen

- [Anprobe erstellen](/docs/generate): jedes Feld und jede Antwort
- [Fehler](/docs/errors) und [Einschränkungen](/docs/limits)
- [Asynchrone Aufgaben, Stapelverarbeitung und Webhooks](/docs/async)
- [API-Status](/status) und die [OpenAPI-Spezifikation](/api/v1/openapi.json)
- [Daten und Datenschutz](/docs/data-privacy) sowie die [Datenverarbeitungsvereinbarung](/dpa)
