E-commerce
25 mars 2025
Lorsqu'une commande nécessite un fichier (logo pour gravure, justificatif, brief PDF, photo pour retouche), l'expérience idéale reste dans le parcours natif : checkout ou compte client, sans email de secours ni formulaire externe peu fiable. Les extensions d'interface Shopify Checkout UI et Customer Account UI exposent le composant DropZone : zone de dépôt ou sélection de fichiers, aligné sur le design system. Ce guide résume le rôle du composant, le flux technique jusqu'au stockage dans Shopify, les limites documentées côté fichiers, et les exigences de sécurité recommandées par l'OWASP. Les passages suivants renvoient vers la documentation officielle shopify.dev et le Centre d'aide Shopify (fichiers). Pour la donnée métier, croisez avec notre guide metafields et metaobjects.
Sommaire
Qu'est-ce que le composant DropZone ?
Le DropZone est un composant de formulaire proposé dans les extensions d'interface Shopify pour le checkout et le compte client. Il permet à l'acheteur d'ajouter des fichiers par glisser-déposer ou par sélection via le dialogue natif du navigateur. La documentation des extensions Checkout UI en décrit les propriétés (libellé, types acceptés, multi-fichiers, état d'erreur, etc.) dans la section des composants de formulaires : voir la fiche DropZone (Checkout UI extensions, API 2025-04).
Le composant gère l'interaction côté boutique : il ne remplace pas à lui seul la persistance du fichier ni l'association à la commande. Le stockage du fichier et l'enregistrement d'une référence (URL, identifiant) relèvent d'un backend et des API Admin, conformément à la documentation GraphQL sur les uploads.
Checkout UI, Customer Account UI et périmètre
Les Checkout UI extensions s'affichent dans le tunnel de paiement selon les cibles d'extension autorisées par Shopify (blocs, en-têtes, etc., selon votre plan et la configuration). Les Customer Account UI extensions s'affichent dans le nouvel espace compte client. Le DropZone peut servir dans l'un ou l'autre contexte lorsque votre application en a besoin : le principe reste identique (sélection de fichiers), mais les règles de ciblage et de déploiement diffèrent. Vérifiez toujours la version d'API et la liste des composants disponibles pour votre cible d'extension au moment du développement.
Cas d'usage e-commerce
Personnalisation : logos, visuels à imprimer, fichiers vectoriels.
Vérification : pièce d'identité ou justificatif lorsque votre processus légal l'exige (avec cadre RGPD et finalité claire).
Brief : PDF de spécifications pour une prestation ou une commande sur mesure.
Instructions : document joint en complément d'instructions de livraison structurées.
Dans tous les cas, la valeur ajoutée est la continuité du parcours : le client comprend ce qu'on attend, quand, et sous quel format.
Architecture : de l'interface au fichier stocké
Une implémentation complète combine quatre couches :
Couche | Rôle | Technologie typique |
|---|---|---|
Interface | Sélection, validation basique, UX | DropZone dans l'extension Checkout ou Customer Account |
Transport | Envoi sécurisé du fichier vers votre serveur ou flux orchestré | HTTPS, appel depuis un backend dédié |
Stockage Shopify | Dépôt du fichier dans l'espace fichiers du marchand | Mutation |
Liaison métier | Rattacher l'URL ou l'identifiant à la commande ou au client | Metafields, metaobjects selon votre modèle |
La mutation stagedUploadsCreate crée des cibles d'upload temporaires et sécurisées : c'est la première étape du processus d'upload en deux temps décrit par Shopify. La documentation précise que cette approche améliore la fiabilité pour les fichiers volumineux, les médias et les imports, et que l'URL retournée sert ensuite de originalSource à des mutations comme fileCreate après upload effectif.
Implémentation : étapes techniques
1. Interface DropZone
Configurez le composant avec les propriétés documentées : types acceptés (MIME ou extensions), gestion multi-fichiers si besoin, libellés et messages d'erreur explicites. Prévoyez un retour visuel pendant l'envoi (spinner, progression) : un upload silencieux dégrade la confiance.
2. Backend obligatoire
Les appels à l'API Admin (création de cibles d'upload, création de fichier, écriture de metafields) doivent s'exécuter côté serveur avec des jetons d'accès protégés. N'exposez jamais les secrets d'API dans le bundle de l'extension affiché côté client.
3. Staged upload puis fileCreate
Enchaînez : obtenir la cible via stagedUploadsCreate, téléverser le fichier vers l'URL fournie avec les paramètres d'authentification, puis créer l'asset fichier via fileCreate en utilisant la resourceUrl comme indiqué dans la documentation de la mutation.
4. Metafields
Stockez une référence stable (URL du fichier, GID) sur la commande ou le client selon votre besoin métier, via les mutations adaptées. Documentez le schéma pour les équipes support.
Pour l'outillage global (CLI, prévisualisations), appuyez-vous sur les ressources de développement Shopify.
Détail du flux GraphQL côté Admin
Après réception du fichier sur votre serveur, le flux standard suit la documentation Shopify : la mutation stagedUploadsCreate prend une entrée décrivant le fichier (ressource, nom, taille, type de contenu selon les champs requis). La réponse fournit une URL de téléversement et des paramètres à inclure dans la requête HTTP vers le stockage temporaire. Une fois l'upload terminé, vous utilisez la resourceUrl comme originalSource dans fileCreate pour créer l'actif fichier exploitable dans l'admin. Ce schéma en deux étapes existe précisément pour fiabiliser les gros fichiers et sécuriser le transfert.
Les erreurs userErrors retournées par les mutations doivent être journalisées côté serveur et traduites en message utilisateur compréhensible sans fuite d'information technique. Prévoyez des tentatives limitées et un délai raisonnable pour les gros fichiers afin d'éviter les blocages de session checkout.
Checkout extension et extension compte client : nuances
Thème | Checkout UI | Customer Account UI |
|---|---|---|
Moment | Pendant le paiement | Après authentification au compte |
Donnée disponible | Panier, lignes, contexte de commande en cours | Profil client, historique selon permissions |
Contrainte UX | Temps court, moindre tolérance à l'erreur | Peut permettre reprise ou complément plus tard |
Cas typique | Fichier indispensable pour finaliser | Mise à jour de documents sur dossier ouvert |
Le composant DropZone reste le même paradigme ; change le contexte métier et les objets GraphQL que vous mettez à jour après coup.
Sessions, secrets et bonnes pratiques Shopify
Les extensions s'exécutent dans un environnement contrôlé : vos appels vers votre backend doivent utiliser des mécanismes d'authentification prévus par la plateforme (par exemple échange de jetons session selon le modèle d'app). Ne stockez jamais la clé API Admin dans le code source versionné. Limitez les scopes OAuth au strict nécessaire (fichiers, commandes, metafields). Révoquez et faites tourner les secrets en cas de fuite suspectée.
Données sensibles et conformité
Les fichiers peuvent contenir des données personnelles ou des données de santé : la minimisation s'impose (ne collectez que le nécessaire), ainsi qu'une politique de rétention et de suppression. L'OWASP rappelle aussi les risques si les fichiers sont ensuite accessibles publiquement sans contrôle : exposition, contenus illicites, déni de service par téléchargements répétés. Si vous exposez une URL, assurez-vous qu'elle est conforme à votre politique de confidentialité et aux droits des personnes.
Observabilité et support
Prévoyez des identifiants de corrélation entre la tentative d'upload côté boutique et l'entrée dans vos journaux serveur : lorsqu'un client contacte le support, vous pourrez retrouver l'échec sans rejouer toute la commande. Stockez la taille du fichier, le type déclaré, le type validé serveur, et le statut final (succès, rejet, timeout).
Limites et formats : ce que dit Shopify
Même lorsque l'upload transite par votre application, les fichiers finissant dans l'admin Shopify sont soumis aux règles du Centre d'aide. Pour les fichiers génériques (hors HTML) destinés au téléchargement, la documentation indique une taille maximale de 20 Mo et des formats larges sur les forfaits payants, avec des restrictions sur les essais gratuits. Pour les images, le même plafond de 20 Mo est indiqué, avec des contraintes de résolution et de formats listés dans la page Téléverser et gérer les fichiers (section exigences de fichiers).
Votre extension doit afficher des consignes claires (taille max, formats) et refuser côté client les fichiers hors périmètre ; la validation serveur reste indispensable.
Sections complémentaires
Sécurité des uploads : principes OWASP
L'OWASP rappelle que les téléversements sont une surface d'attaque : faux fichiers, contenus malveillants, saturation d'espace. La feuille de route recommandée insiste sur une liste d'extensions autorisées, une validation d'entrée, et une défense en profondeur.
« L'application doit être capable de repousser les fichiers fictifs et malveillants de manière à préserver la sécurité de l'application et des utilisateurs. »
OWASP File Upload Cheat Sheet (traduction libre)
À appliquer concrètement : liste blanche d'extensions alignée sur votre usage métier, validation serveur (taille, type réel, nom de fichier), limitation du débit, et politique de stockage conforme à la sensibilité des documents (identité, santé, etc.). Le Content-Type annoncé par le navigateur n'est pas une preuve : l'OWASP signale qu'il peut être falsifié ; il ne doit pas suffire seul.
UX, mobile et accessibilité
Le MDN (documentation web) documente le comportement de l'élément input type="file" : le navigateur fournit une interface de sélection de fichiers ; les attributs accept et multiple permettent de guider l'utilisateur. Sur mobile, le glisser-déposer est souvent secondaire : le bouton de sélection et un libellé clair restent centraux.
Prévoyez des messages courts si un fichier est rejeté (type ou taille trop importante) et évitez de bloquer le checkout sans alternative lorsque le fichier est optionnel.
Limitations et points de vigilance
Surface d'extension : le bundle et les cibles autorisées sont contraintes par les règles Shopify ; vérifiez la compatibilité avec votre plan et votre version d'API.
Fonctionnalité « prévisualisation » : une prévisualisation riche d'image peut nécessiter un développement supplémentaire hors composant par défaut.
Style : le rendu respecte le design system de l'extension ; testez sur des thèmes réels.
Conformité : les documents personnels exigent une base légale, une durée de conservation et des accès internes maîtrisés.
Tests et mise en production
Tester les fichiers limites (taille proche du plafond, types autorisés et refusés).
Tester sur mobile iOS et Android : sélection depuis la galerie, fichiers cloud.
Vérifier les parcours d'erreur réseau (timeout, reprise).
Contrôler que les fichiers apparaissent bien dans l'admin et que les metafields sont lisibles par le support.
Checklist développeur avant mise en ligne
Version d'API Checkout UI / Customer Account UI figée et testée sur boutique de développement.
Scopes OAuth minimaux validés en revue de code.
Tests de charge légers sur
stagedUploadsCreate: pas de boucle infinie de retentatives côté client.Politique de nommage des fichiers côté serveur (UUID ou préfixe) pour éviter collisions et traversées de répertoires.
Page mentions légales / confidentialité à jour si collecte de documents d'identité.
Alternatives si le DropZone ne suffit pas
Pour des volumes très importants, des formats hors liste Shopify, ou une chaîne de traitement externe (virus scan, conversion), vous pouvez déléguer le stockage à un fournisseur d'objets tout en conservant un point d'entrée UX dans l'extension : l'extension envoie alors un jeton signé vers votre API, qui orchestre l'upload distant et ne stocke dans Shopify qu'une référence ou un identifiant dans un metafield. Ce modèle complexifie l'architecture mais respecte des contraintes de conformité ou de performance.
Pour des besoins purement conversationnels sans fichier structuré, un chatbot peut parfois suffire pour qualifier la demande avant de rediriger vers un parcours avec pièce jointe.
Bonnes pratiques et erreurs fréquentes
Bonnes pratiques
Restreindre
acceptau strict nécessaire pour réduire les risques et le bruit.Valider côté serveur chaque fichier avant traitement métier.
Journaliser les erreurs d'upload sans exposer de secrets dans les messages clients.
Erreurs fréquentes
Erreur | Risque | Correctif |
|---|---|---|
Secrets Admin dans le front | Compromission du magasin | Backend dédié, variables d'environnement |
Confiance uniquement au type MIME client | Upload malveillant | Validation serveur, liste blanche |
Aucun plafond de taille | DoS / coûts | Alignement sur le Help Center + limite applicative |
Intérêt pour votre boutique
Parcours unifié : moins de friction qu'un formulaire externe.
Traçabilité : fichier lié à la commande ou au client dans Shopify.
Évolutivité : vous restez dans l'écosystème extensions et API documentées.
Le gain de conversion dépend de votre offre et de la clarté des consignes : évitez les promesses chiffrées génériques sans test A/B sur votre audience.
Compléter avec un chatbot
Les pièces jointes répondent à un besoin transactionnel ; un chatbot IA comme Qstomy peut aider avant le checkout pour expliquer formats acceptés, délais ou options de personnalisation, et réduire les abandons liés au doute. Découvrez l'intégration chatbot IA sur Shopify et notre guide chatbot e-commerce.
Le plan Shopify change-t-il les règles de fichiers ?
Les formats acceptés sur essai et sur forfait payant peuvent différer : le Centre d'aide décrit notamment des restrictions sur les essais et la vérification d'e-mail pour certains types. Vérifiez la page française à jour avant de promettre des formats à vos clients.
Que faire si fileCreate échoue après upload ?
Vérifiez que la resourceUrl correspond bien au fichier téléversé, que la taille annoncée était correcte et que le type est pris en charge. Journalisez le message userErrors et proposez un message générique côté boutique.
Plusieurs fichiers sur une même ligne de commande
Prévoyez un modèle de données clair : liste d'identifiants de fichiers dans un metafield JSON, ou plusieurs metafields nommés, et testez la limite pratique côté UX (temps d'upload, abandon).
Résumé
Le DropZone des extensions Shopify sert de point de collecte de fichiers dans le checkout ou le compte client. Il doit être combiné à un backend utilisant les mutations Admin stagedUploadsCreate et fileCreate, puis à des metafields pour lier la ressource à la commande ou au client. Respectez les limites du Centre d'aide (tailles et formats), appliquez les bonnes pratiques OWASP, et testez sur mobile. Tenez votre implémentation alignée sur la version d'API documentée sur Documentez la version d'API testée et les identifiants de build dans votre dépôt pour faciliter les audits ultérieurs et les mises à jour mineures. shopify.dev.
FAQ
Comment limiter les types de fichiers ?
Utilisez la propriété d'acceptation du DropZone (types MIME ou extensions) et complétez par une validation serveur conforme à la liste blanche métier.
Faut-il un backend ?
Oui pour les appels Admin et les secrets : l'extension ne doit pas embarquer les jetons d'accès à la boutique.
Quelle taille maximale ?
Pour les fichiers génériques et les images, le Centre d'aide indique couramment un plafond de 20 Mo ; vérifiez la page à jour pour votre contexte.
Le glisser-déposer est-il obligatoire ?
Non : la sélection de fichier native reste l'option principale sur mobile ; prévoyez un bouton clair.
Données d'identité
Prévoyez information sur la finalité, durée de conservation et accès ; la conformité RGPD est un prérequis indépendant du composant.
Aller plus loin
25 mars 2025
