Search docs

Search the TryOnCloud API docs

Plattformen

Shopify Hydrogen (Headless)

Headless Shopify auf Hydrogen und Oxygen: eine Server-Route und eine Schaltfläche auf der Produktseite.

Code-Beispiele, Endpunkte und Fehlercodes sind in jeder Sprache identisch.

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 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-ShopHeadless (Hydrogen)-Shop
LadenfrontShopify-ThemeIhre React-App auf Oxygen
So wird die Anprobe hinzugefügtInstallieren Sie die Shopify-App und fügen Sie den Block hinzuEine Serverroute und eine Komponente
RechnungsstellungShopify-Tarif, auf Ihrer Shopify-RechnungEntwickler-API-Guthaben, im Voraus bezahlt
LeitfadenShopifyDiese Seite

So funktioniert es

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

BedarfWie
Trennung von Entwicklung und ProduktionErstellen 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 MobilfunknetzenSenden 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üfungJede 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 DatenschutzSenden 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 ProdukteDie Kleideranalyse wird 30 Tage lang zwischengespeichert, sodass wiederholte Anproben desselben Produktfotos etwa 2 Sekunden schneller erfolgen.
KatalogbilderErstellen 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.
Verkehrsspitzen300 Anfragen pro Minute pro Schlüssel und 600 pro Konto. Bitte informieren Sie uns vor einem großen Verkauf oder einer festlichen Produkteinführung, damit wir die Kapazitäten entsprechend planen können.
ÜberwachungAktuelle Erfolgsquote und Geschwindigkeit unter /status, Nutzung pro Schlüssel in Generations (Suche, CSV-Export).
Client-GeneratorenOpenAPI 3.1-Spezifikation unter /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 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. Bei hohem Volumen oder einem Pilotprojekt über mehrere Shops hinweg kontaktieren Sie uns bitte, um unsere Unternehmenspreise zu erfahren.

Verwandte Themen