# Shopify Hydrogen (headless)

Ajoutez une fonctionnalité d'essayage virtuel à une **boutique Shopify headless** créée avec Hydrogen et hébergée sur Oxygen. Cela nécessite une seule route de serveur et un seul composant de page produit, et la clé API n'est jamais transmise au navigateur.

## Que signifie « sans tête » ?

Une boutique Shopify classique affiche ses pages à l'aide d'un **thème**. Notre [application Shopify](/docs/shopify) ajoute le bouton « Essayer » à ce thème sans nécessiter de code.

Une boutique **headless** utilise Shopify pour les produits, le panier, le processus de paiement et les transactions, mais la vitrine que voient les clients est une **application React** distincte, développée par vos développeurs. Hydrogen est le framework d’Shopify dédié à cette application, et Oxygen est la solution d’hébergement proposée par Shopify pour celle-ci. Comme il n’y a pas de thème, les blocs d’application de thème n’apparaissent pas ; une boutique « headless » intègre donc la fonctionnalité d’essayage via l’**API développeur**.

|  | Boutique de thèmes | Boutique « Headless » (de Hydrogen) |
|---|---|---|
| Vitrine | Thème Shopify | Votre application React sur Oxygen |
| Comment ajouter la fonctionnalité « Essayer » | Installez l'application Shopify, ajoutez le bloc | Une route de serveur et un composant |
| Facturation | Formule Shopify, sur votre facture Shopify | Crédits API pour développeurs, prépayés |
| Guide | [Shopify](/docs/shopify) | Cette page |

## Comment ça marche ?

```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. Le client clique sur **Essayer** sur la page d'un produit, puis prend ou importe une photo.
2. Le navigateur envoie la photo et l'URL de l'image du produit vers **votre** route Hydrogen.
3. Votre route appelle TryOnCloud à l'aide de votre clé secrète et récupère l'image finale, généralement en 20 secondes environ.
4. Le client s'imagine en train de porter le produit. Aucune donnée n'est enregistrée par TryOnCloud, sauf si vous activez la fonction de sauvegarde des résultats.

## 1. Obtenir une clé API

Inscrivez-vous, accédez à **Tableau de bord > Clés API** et créez une clé. Celle-ci commence par `tk_dev_v1_` et n'est affichée dans son intégralité qu'une seule fois. Votre compte vous donne droit à des essais gratuits, et le mode test (`?mock=true`) est toujours gratuit.

## 2. Enregistrer la clé dans Oxygen

Dans l'interface d'administration Shopify, accédez à **Hydrogen > Votre boutique > Paramètres de la boutique > Environnements et variables**, puis ajoutez une variable **secrète** :

```bash
TRYONCLOUD_API_KEY=tk_dev_v1_your_key_here
```

Pour le développement local, récupérez-le dans le fichier `.env` à l'aide de la commande `npx shopify hydrogen env pull`, ou ajoutez-le manuellement au fichier `.env`. Ajoutez-le ensuite au type `Env` dans le fichier `env.d.ts` afin que `context.env` soit typé :

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

## 3. Ajouter la route du serveur

Créez le fichier `app/routes/api.try-on.tsx`. Hydrogen le met à disposition à l'adresse `/api/try-on`. Cette route n'accepte que les images de produits provenant de votre propre CDN Shopify, ce qui empêche quiconque d'utiliser votre clé pour essayer des images au hasard.

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

Dans un ancien projet Hydrogen basé sur Remix, importez plutôt les types depuis `@shopify/remix-oxygen` : `import type { ActionFunctionArgs } from "@shopify/remix-oxygen"`, et définissez le type de l'action comme `({ request, context }: ActionFunctionArgs)`.

> **Remarque :** un essai dure environ 20 secondes. Laissez la requête ouverte et n’ajoutez pas de délai d’expiration plus court au début de cette route. Les essais ayant échoué sont automatiquement remboursés.

## 4. Ajouter le bouton à la page du produit

Créez le fichier `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>
  )
}
```

Ensuite, affichez-la dans votre route « produit » (`app/routes/products.$handle.tsx`) avec l'image de la variante sélectionnée, en utilisant l'image principale du produit à défaut :

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

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

Assurez-vous que votre requête de produit demande `image { url }` pour la variante et `featuredImage { url }` pour le produit.

## 5. Autorisez l'image obtenue dans votre CSP

Hydrogen applique une politique de sécurité de contenu (CSP) stricte. Le résultat s'affiche à partir d'une URL de type `blob:` ; vous devez donc ajouter `blob:` à `imgSrc` dans `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:"],
})
```

Aucune modification de `connectSrc` n'est nécessaire : le navigateur communique uniquement avec votre propre route `/api/try-on`.

## 6. Tester avant la mise en service

1. Configurez l'itinéraire en mode test pendant la création : utilisez `https://www.tryoncloud.com/api/v1/generate?mock=true`. Cela permet d'effectuer toutes les vérifications et de renvoyer la photo telle quelle, sans utiliser de crédit.
2. Essayez quelques articles : hauts, robes, saris, ensembles kurta et bas.
3. Essayez avec une photo trop volumineuse et un fichier qui n'est pas une image, puis vérifiez les messages d'erreur.
4. Supprimez `?mock=true` et effectuez de véritables essais.

## 7. Le mettre en œuvre à l'échelle du marché de détail

Les grands catalogues et les magasins nombreux ont besoin d'un peu plus qu'un simple bouton. Toutes ces fonctionnalités sont intégrées :

| Besoin | Comment |
|---|---|
| Séparation entre le développement et la production | Créez une clé par environnement dans la section **Clés API**. Attribuez à la clé de test une **limite de crédit mensuelle** et une **date d'expiration**, afin que les tests ne puissent jamais utiliser les crédits destinés à la production. |
| Nouvelles tentatives sécurisées sur les réseaux mobiles | Envoyez une clé d'`Idempotency-Key` (la `tryOnId` ci-dessus). Une nouvelle tentative du même essayage après une perte de connexion n'est facturée qu'une seule fois, et le bouton est désactivé pendant l'essayage ; ainsi, un double appui ne peut pas en lancer un deuxième. |
| Assistance et audit | Chaque réponse comporte un en-tête `X-Request-Id`. Enregistrez-le avec vos erreurs et indiquez-le-nous. |
| Demandes relatives à la confidentialité des clients | Envoyez `customer_id`, puis supprimez les données de ce client à l'aide de la commande `DELETE /api/v1/customers/:id`. Par défaut, les photos des clients ne sont jamais enregistrées. |
| Produits populaires | L'analyse du vêtement est mise en cache pendant 30 jours ; ainsi, les essais successifs de la même photo de produit sont environ 2 secondes plus rapides. |
| Images du catalogue | Créez des photos sur mannequin pour plusieurs références à l'aide de la méthode `POST /api/v1/batches` (jusqu'à 500 par lot) et recevez un webhook signé dès que chacune d'entre elles est prête. Consultez les sections consacrées [aux tâches asynchrones, aux lots et aux webhooks](/docs/async). |
| Heures de pointe | 300 requêtes par minute et par clé, et 600 par compte. Avant une grande promotion ou le lancement d'une campagne festive, [prévenez-nous](/contact) afin que nous puissions prévoir la capacité nécessaire. |
| Suivi | Taux de réussite et vitesse en temps réel sur [/status](/status), utilisation par clé dans **Generations** (recherche, exportation CSV). |
| Générateurs de clients | Spécification OpenAPI 3.1 disponible à l'adresse [/api/v1/openapi.json](/api/v1/openapi.json). |

## 8. Liste de contrôle pour la mise en service

- `TRYONCLOUD_API_KEY` est une variable **secrète** dans l'environnement Oxygen **de production**
- La clé n'apparaît nulle part dans le code du navigateur ni dans le code source de la page.
- Suppression de `?mock=true`` de la route
- Ajout de `blob:` à `imgSrc`
- Les images des produits proviennent de `cdn.shopify.com` et présentent clairement le vêtement
- Ligne de confidentialité affichée à côté du bouton (photo utilisée uniquement pour l'essayage, non enregistrée)
- Crédits rechargés. Nous envoyons automatiquement un e-mail au titulaire du compte lorsque le solde atteint 10 % du montant du dernier achat (soit au moins 20 crédits).
- Une clé de production distincte de la clé de préproduction, chacune associée à la limite de crédit mensuelle de votre choix
- La clé `Idempotency-Key` est envoyée à chaque essai, et l'en-tête `X-Request-Id` est enregistré en cas d'erreur

## Chronologie

Une équipe d'Hydrogen a généralement besoin d'**une à deux semaines** pour mettre en place un projet pilote : une journée pour ajouter la clé et effectuer des tests en mode simulation, deux ou trois jours pour l'itinéraire et le bouton de la page produit, et le reste pour l'assurance qualité sur des produits réels et un déploiement progressif.

## Les magasins aussi

Vous disposez également de magasins physiques ? La [borne en magasin](/docs/kiosk) permet d'essayer des vêtements sur un écran ou un miroir intelligent, notamment en demandant aux clients de tenir un vêtement devant la caméra. Elle utilise le même compte.

## Tarifs

Les boutiques « Headless » utilisent **des crédits API pour développeurs** : prépayés, sans date d'expiration, et les essais ratés ne sont jamais facturés. Consultez [nos tarifs](/pricing#developer-api). Pour les volumes importants ou un projet pilote impliquant plusieurs boutiques, [contactez-nous](/contact) pour obtenir nos tarifs entreprise.

## À lire également

- [Générer un aperçu](/docs/generate) : chaque champ et chaque réponse
- [Erreurs](/docs/errors) et [limites](/docs/limits)
- [Tâches asynchrones, traitements par lots et webhooks](/docs/async)
- [État de l'API](/status) et [spécification OpenAPI](/api/v1/openapi.json)
- [Données, confidentialité](/docs/data-privacy) et [accord](/dpa) sur [le traitement des données](/dpa)
