Search docs

Search the TryOnCloud API docs

Plateformes

Shopify Hydrogen (headless)

Shopify « headless » sur Hydrogen et Oxygen : une route serveur et un bouton sur la page produit.

Les exemples de code, les points de terminaison et les codes d'erreur sont identiques dans tous les langages.

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 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èmesBoutique « Headless » (de Hydrogen)
VitrineThème ShopifyVotre application React sur Oxygen
Comment ajouter la fonctionnalité « Essayer »Installez l'application Shopify, ajoutez le blocUne route de serveur et un composant
FacturationFormule Shopify, sur votre facture ShopifyCrédits API pour développeurs, prépayés
GuideShopifyCette page

Comment ça marche ?

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

BesoinComment
Séparation entre le développement et la productionCré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 mobilesEnvoyez 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 auditChaque réponse comporte un en-tête X-Request-Id. Enregistrez-le avec vos erreurs et indiquez-le-nous.
Demandes relatives à la confidentialité des clientsEnvoyez 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 populairesL'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 catalogueCré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.
Heures de pointe300 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 afin que nous puissions prévoir la capacité nécessaire.
SuiviTaux de réussite et vitesse en temps réel sur /status, utilisation par clé dans Generations (recherche, exportation CSV).
Générateurs de clientsSpécification OpenAPI 3.1 disponible à l'adresse /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 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. Pour les volumes importants ou un projet pilote impliquant plusieurs boutiques, contactez-nous pour obtenir nos tarifs entreprise.

À lire également