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è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 | Cette page |
Comment ça marche ?
POST /api/try-on (photo + product image URL)
POST /api/v1/generate (X-API-KEY)
200 image/png
200 image/png
- Le client clique sur Essayer sur la page d'un produit, puis prend ou importe une photo.
- Le navigateur envoie la photo et l'URL de l'image du produit vers votre route Hydrogen.
- 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.
- 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 :
TRYONCLOUD_API_KEY=tk_dev_v1_your_key_herePour 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é :
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.
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).
4. Ajouter le bouton à la page du produit
Créez le fichier app/components/TryOnButton.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 :
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 :
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
- 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. - Essayez quelques articles : hauts, robes, saris, ensembles kurta et bas.
- Essayez avec une photo trop volumineuse et un fichier qui n'est pas une image, puis vérifiez les messages d'erreur.
- Supprimez
?mock=trueet 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. |
| 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 afin que nous puissions prévoir la capacité nécessaire. |
| Suivi | Taux de réussite et vitesse en temps réel sur /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. |
8. Liste de contrôle pour la mise en service
TRYONCLOUD_API_KEYest 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.comet 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-Keyest envoyée à chaque essai, et l'en-têteX-Request-Idest 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
- Générer un aperçu : chaque champ et chaque réponse
- Erreurs et limites
- Tâches asynchrones, traitements par lots et webhooks
- État de l'API et spécification OpenAPI
- Données, confidentialité et accord sur le traitement des données