Téléversement de médias pour les applications de commerce Angular

Points clés à retenir

Créez les paramètres de téléversement signés sur le backend et limitez leur portée à un Template approuvé.
Définissez explicitement qui gère le cycle de vie d’Uppy afin que les changements de route ne laissent pas d’abonnements actifs ni ne dupliquent les téléversements.
Représentez le téléversement et le traitement par des états de progression distincts.

Les applications de commerce ont souvent besoin de permettre aux marchands, aux fournisseurs ou aux clients de téléverser des médias. Le frontend devrait proposer une sélection accessible et un suivi de la progression, tandis que les secrets, la politique de validation, le traitement et le stockage restent sous le contrôle du serveur.

L’essentiel

Conservez l’identifiant de l’Assembly de manière persistante afin que l’interface puisse retrouver l’état de l’opération après une navigation ou une actualisation.

Définir les limites de responsabilité du téléversement avant de choisir les composants

Une application de commerce Angular peut accepter des images de marchands, de fournisseurs, d’évaluateurs ou de clients, mais chaque flux de travail implique des permissions et des conséquences différentes en matière de publication. Avant de créer le sélecteur, définissez qui peut téléverser, quel objet du catalogue cette personne peut modifier, les médias acceptés, les limites, les dérivés requis, les règles d’approbation et le stockage final. Le navigateur devrait recueillir les fichiers et afficher l’état. Un backend de confiance devrait autoriser l’action, signer les paramètres de traitement et décider si les médias traités sont intégrés au catalogue.

Le transfert direct du navigateur au service de téléversement évite que les données des fichiers volumineux transitent par le serveur de l’application Angular, ce qui réduit la bande passante utilisée par l’application et la durée des requêtes. Cela ne retire pas le backend du modèle de sécurité. Le backend associe toujours la requête à un utilisateur authentifié et à un produit, émet des paramètres approuvés à courte durée de validité, reçoit des informations de fin de traitement fiables et met à jour l’enregistrement dans le système de commerce. Dans cette architecture, Transloadit prend en charge la réception et le traitement des fichiers, mais pas le rendu Angular, la logique du catalogue, les paniers, le passage en caisse ni les stocks.

Navigateur

Sélectionne les fichiers, fournit un retour local, transfère les octets et présente les états du téléversement et du traitement.

Backend de l’application

Authentifie les utilisateurs, autorise les actions sur les produits, signe les requêtes, vérifie la fin du traitement et enregistre l’état du catalogue.

Service de traitement

Valide et transforme les médias acceptés conformément au flux de travail approuvé.

Stockage persistant

Conserve les fichiers de sortie publiables que la boutique en ligne ou une couche de diffusion distincte peut servir.

Modéliser le téléversement par une machine à états permettant la reprise

Utilisez des états explicites tels que inactif, sélection en cours, validation en cours, en attente d’autorisation, téléversement en cours, en pause, traitement en cours, terminé, échoué et annulé. Conservez un identifiant local stable pour l’opération et, une fois l’Assembly créée, son identifiant. La progression du transfert réseau et celle du traitement côté serveur sont des signaux distincts et ne devraient pas être réunies dans un pourcentage trompeur. Un fichier peut être entièrement téléversé alors que son redimensionnement ou son encodage vidéo est encore en cours.

Décidez quelle couche est responsable d’un téléversement actif lorsque le composant est détruit. Un composant propre à une route peut l’annuler et libérer ses ressources lors de la navigation, tandis qu’un service de téléversement dont la durée de vie est plus longue peut délibérément préserver l’opération d’une route à l’autre. Chaque choix peut être valable, mais une responsabilité laissée au hasard entraîne des abonnements non libérés, des gestionnaires d’événements dupliqués ou des téléversements qui continuent sans commandes visibles. Exposez un état de vue immuable à l’aide de signaux Angular ou de flux RxJS et centralisez les transitions au lieu de laisser plusieurs callbacks d’événements modifier des indicateurs sans lien entre eux.

État du transfert

Représente les octets envoyés, la pause, la reprise, l’annulation et les erreurs réseau.

État du traitement

Représente le travail asynchrone du serveur après réception d’une quantité suffisante de données d’entrée.

État de la publication

Représente l’approbation par l’application et l’association au catalogue, qui peuvent intervenir après la réussite du traitement.

Émettre des paramètres d’Assembly signés et soumis à des restrictions

Ne placez jamais l’Auth Secret de Transloadit dans le code source Angular, dans une configuration d’exécution transmise au navigateur ni dans un bundle généré. Le backend devrait vérifier la session de l’utilisateur et ses permissions sur le produit cible, construire des paramètres d’Assembly approuvés avec une expiration proche et un nonce unique, signer la charge utile sérialisée exacte, puis renvoyer les paramètres et la signature. Le navigateur peut les soumettre, mais il ne peut pas modifier un champ protégé sans invalider la signature.

Utilisez un Template enregistré pour définir la structure du flux de travail et définissez allow_steps_override sur false lorsque les utilisateurs du navigateur ne doivent pas modifier ses Steps. La requête signée peut toujours contenir des champs à valeurs encadrées, tels qu’un identifiant de produit ou un choix de variante approuvé. Validez ces valeurs avant la signature, puis à nouveau avant d’utiliser les résultats. Conservez les informations d’identification pour le stockage dans les informations d’identification de Template, avec les permissions minimales nécessaires, au lieu de les envoyer au client. Une Auth Key identifie le Workspace, mais ce sont le secret et le processus de signature qui protègent l’intégrité de la requête.

Authentifier

Exigez une identité valide dans l’application avant de générer une autorisation de téléversement.

Autoriser

Confirmez que cette identité peut ajouter des médias au marchand, au produit ou à la commande visés par la requête.

Restreindre

Choisissez côté serveur le Template, la politique applicable aux fichiers, les limites, le périmètre de destination, l’expiration et les champs approuvés.

Auditer

Enregistrez l’utilisateur, le produit, le nonce et l’identifiant de l’Assembly créée sans journaliser les secrets ni les charges utiles signées complètes.

Intégrer Uppy avec un cycle de vie géré par Angular

Uppy peut assurer la sélection, le suivi de la progression et le téléversement avec reprise, tandis que son plugin Transloadit crée et suit une Assembly. Créez l’instance d’Uppy uniquement dans un environnement de navigateur, car le rendu serveur d’Angular ne fournit ni objet window ni DOM, même si l’environnement d’exécution Node.js fournit les variables globales File et Blob qui peuvent suffire à faire passer des vérifications d’environnement naïves. Évitez de la construire pendant l’évaluation d’un module ou dans un chemin d’exécution de composant rendu côté serveur. Montez son interface lorsque la cible est présente et traduisez ses événements en état de l’application au lieu de considérer le DOM interne de l’outil de téléversement comme la source de vérité.

Instanciez un seul outil de téléversement pour le périmètre de responsabilité prévu, enregistrez chaque écouteur une seule fois et supprimez les écouteurs ainsi que les éléments d’interface montés lors d’un démontage explicite. Si un service singleton est responsable des téléversements actifs, exposez une interface restreinte aux composants et conservez un état par opération. Si le composant est responsable de l’instance, détruisez-la à la sortie de la route et informez l’utilisateur que la navigation annule l’opération. Ne créez pas une nouvelle instance à chaque passage de détection des changements ou à chaque abonnement, car des instances dupliquées peuvent soumettre les mêmes fichiers et signaler des progressions contradictoires.

Vérification de l’exécution dans le navigateur

N’initialisez le code de téléversement qu’après avoir confirmé que le composant s’exécute dans le navigateur.

Un seul responsable

Confiez à un seul composant ou service la responsabilité de la création de l’instance, de l’enregistrement des événements et du démontage.

Adaptateur d’état

Convertissez les événements de l’outil de téléversement en états typés de l’application que les modèles de vue peuvent afficher et tester.

Utiliser la reprise des transferts sans promettre une récupération impossible

Le protocole tus crée une ressource de téléversement, envoie les octets du fichier au moyen de requêtes tenant compte du décalage et peut interroger le serveur pour connaître le dernier décalage accepté après une interruption. Cela évite de recommencer un téléversement volumineux simplement parce que la connexion a été coupée. La possibilité de reprendre un transfert ne signifie pas une récupération automatique après tout événement du navigateur ou changement de route. L’application doit conserver l’URL de téléversement et suffisamment d’informations locales sur le fichier, et les politiques de confidentialité ou de stockage du navigateur peuvent malgré tout empêcher la restauration.

Définissez le comportement de nouvelle tentative et d’annulation pour chaque catégorie d’échec. Une erreur réseau temporaire peut permettre une reprise après attente, une signature expirée peut nécessiter une nouvelle autorisation du backend, et un rejet de validation côté serveur exige un fichier corrigé. Appliquez un délai croissant entre les tentatives et limitez leur nombre au lieu de renvoyer indéfiniment une charge utile invalide. Lorsque plusieurs fichiers appartiennent à la même opération, décidez si un seul rejet fait échouer toute la soumission du produit ou si les fichiers valides peuvent continuer. Reflétez cette politique à la fois dans le Template et dans l’interface.

Mettre en pause

Conservez l’opération en cours et indiquez qu’aucun octet n’est transféré.

Reprendre

Vérifiez le décalage accepté et poursuivez le transfert restant lorsque l’autorisation est toujours valide.

Réessayer

Créez une nouvelle tentative contrôlée uniquement pour les erreurs que l’application classe comme récupérables.

Annuler

Arrêtez volontairement l’opération et précisez les conséquences pour le catalogue et les fichiers temporaires.

Créer une expérience de téléversement accessible

Le glisser-déposer devrait compléter un champ de sélection de fichiers ou un bouton muni d’un libellé, sans le remplacer. Chaque action nécessite une commande utilisable au clavier et un indicateur de focus visible. Expliquez les formats acceptés ainsi que les limites de quantité et de taille avant la sélection. Associez les erreurs au fichier concerné, fournissez un récapitulatif des erreurs pour les soumissions de plusieurs fichiers et évitez de signaler un échec uniquement par la couleur. Selon sa fonction, un aperçu nécessite un texte alternatif utile ou un traitement clairement décoratif.

Annoncez les changements d’état importants au moyen d’une région dynamique appropriée, sans commenter chaque octet. Les utilisateurs ont généralement besoin de savoir que le téléversement a commencé, a été mis en pause, a échoué, a repris, est passé au traitement et s’est terminé. Gardez le pourcentage visible sous forme de texte et exposez une valeur de progression accessible. L’annulation devrait demander confirmation lorsqu’elle fait perdre une quantité importante de travail. Si le traitement continue après la navigation, fournissez un emplacement persistant où consulter son état afin que l’utilisateur n’ait pas à garder le composant d’origine ouvert.

Avant la sélection

Indiquez les médias autorisés, les limites, le traitement prévu et si la publication nécessite un examen.

Pendant le transfert

Fournissez une progression par fichier, des commandes de pause ou d’annulation et des messages d’erreur réseau permettant d’agir.

Après le transfert

Distinguez le traitement et l’approbation de la fin du téléversement et fournissez un moyen de revenir consulter l’état.

Finaliser les opérations par un circuit asynchrone de confiance

Pour les opérations courtes sur les images, le navigateur peut attendre l’encodage et utiliser le statut de l’Assembly terminée. Pour les flux de travail de commerce plus longs, il est généralement utile de configurer le client pour qu’il n’attende pas et de définir un notify_url. Transloadit envoie le statut final de l’Assembly à cet endpoint du backend après la fin du traitement. Le gestionnaire devrait vérifier la signature du webhook avec le secret associé à l’Auth Key de l’Assembly, rejeter les charges utiles invalides et accuser rapidement réception des notifications valides. Les réponses qui n’indiquent pas une réussite peuvent entraîner de nouvelles tentatives d’envoi des notifications ; le gestionnaire doit donc être idempotent.

Conservez l’identifiant de l’Assembly de manière persistante au démarrage de l’opération et associez-le à l’utilisateur et au produit. À la fin du traitement, faites correspondre les résultats aux téléversements à l’aide d’identifiants tels que original_id, et non de leur position dans un tableau, car l’ordre des résultats ne garantit pas cette correspondance. Enregistrez les URL persistantes des fichiers exportés et les métadonnées requises, puis faites évoluer l’état de l’enregistrement des médias du produit. Ne publiez pas les URL temporaires de traitement à l’intention des clients. Si le navigateur manque l’événement de fin de traitement, il devrait retrouver l’état dans la base de données de l’application plutôt que de devenir la seule source faisant autorité.

Vérifier

Authentifiez la charge utile de fin de traitement avant d’accepter son statut ou ses URL.

Dédupliquer

Traitez les notifications répétées pour la même Assembly et le même état terminal comme la même opération.

Corréler

Retrouvez l’enregistrement autorisé de l’application correspondant à l’identifiant d’Assembly conservé avant d’écrire les résultats.

Publier

Ne mettez à jour le catalogue qu’après la production réussie des fichiers de sortie requis et la réussite des éventuels contrôles d’approbation.

Tester les règles, le cycle de vie et les opérations

Testez unitairement l’adaptateur d’état avec des séquences d’événements couvrant la réussite, la mise en pause, les nouvelles tentatives, le rejet, l’annulation, la destruction du composant et les événements de fin dupliqués. Testez le point de terminaison de signature avec des utilisateurs non authentifiés, des produits non autorisés, des champs invalides, des paramètres expirés et des nonces réutilisés. Les tests dans le navigateur devraient utiliser des commandes accessibles pour sélectionner les données de test et couvrir les transferts lents, la navigation, l’actualisation, le rendu côté serveur et l’arrivée d’un webhook après le départ de l’utilisateur.

En préproduction, téléversez des fichiers mal étiquetés, des lots trop volumineux, des images trop petites, des conteneurs corrompus et des médias dont le traitement est long. Confirmez que la validation côté client fournit rapidement des indications, tandis que la validation côté serveur reste la référence. Surveillez les échecs d’autorisation, les transferts abandonnés, la durée de traitement, les nouvelles tentatives de webhook, les erreurs de destination et le coût par flux de traitement. Déclenchez des alertes en cas de files d’attente ou d’échecs persistants, et non à chaque annulation par un utilisateur. Conservez les identifiants expurgés et les classes d’erreurs assez longtemps pour permettre une investigation sans stocker de données personnelles inutiles.

Tests de contrat

Vérifiez la structure de réponse du backend attendue par l’intégration Uppy et le gestionnaire de webhook.

Tests du cycle de vie

Démontrez que les changements de route ne laissent aucun module de téléversement sans nettoyage et n’annulent pas de manière inattendue une opération prise en charge par un service.

Simulations de défaillance

Simulez des pannes de stockage, des notifications dupliquées et des autorisations expirées avant que le trafic de production ne vous y confronte.

Détails techniques à connaître

Le transfert direct du navigateur vers le service de téléversement évite que les octets des fichiers transitent par les serveurs de l’application Angular, mais la signature des requêtes et les décisions relatives aux permissions doivent rester sur un backend de confiance.
RxJS peut modéliser la progression, l’annulation, les nouvelles tentatives et le nettoyage des composants, tandis que le protocole de téléversement avec reprise doit conserver suffisamment d’état pour reprendre après une navigation ou une interruption.
Le rendu côté serveur d’Angular ne dispose ni de l’objet window ni du DOM, même si Node.js fournit les objets globaux File et Blob. L’initialisation du téléversement doit être limitée au code exécuté exclusivement dans le navigateur, sans s’exécuter pendant le rendu côté serveur.
La reprise repose sur la division d’un fichier en transferts pouvant être repris, mais le suivi de progression dans l’application devrait distinguer le prétraitement local, le téléversement réseau et le traitement des médias côté serveur.
Les changements de route et la destruction des composants ne devraient pas laisser silencieusement les téléversements actifs sans responsable, sauf si le produit en transfère délibérément la responsabilité à un service dont la durée de vie est plus longue.
Les champs de sélection de fichiers nécessitent des libellés visibles, un accès au clavier, des récapitulatifs d’erreurs et des annonces de progression, en plus de l’interaction par glisser-déposer.

Une approche pratique

1
Définissez les champs des médias, les limites, les dérivés et les chemins de stockage pour un seul flux de travail produit.
2
Exposez un endpoint du backend qui renvoie des paramètres d’Assembly signés à courte durée de validité.
3
Montez une seule instance d’Uppy, traduisez ses événements en état de l’application et gérez explicitement son nettoyage.
4
Traitez le webhook de fin côté serveur et actualisez l’état du produit à partir d’un enregistrement de confiance.

Un flux de travail multimédia en quatre phases

Quand Transloadit est utile

Intégrez Uppy dans un composant Angular ou une couche indépendante du framework, obtenez des paramètres d’Assembly signés auprès du backend et affichez la progression pendant que Transloadit crée les dérivés des médias produit et les exporte.

Périmètre architectural

Angular fournit les composants de la boutique en ligne et la gestion de l’état. Transloadit gère la réception et le traitement des fichiers, mais pas le panier, le catalogue, le passage en caisse, le framework de rendu ni le backend de commerce.

Questions fréquentes

Une application Angular peut-elle générer la signature Transloadit dans le navigateur ?

Non. La génération de la signature nécessite l’Auth Secret, qui doit rester sur un backend de confiance. Angular devrait demander des paramètres signés à courte durée de validité après que le backend a authentifié l’utilisateur et vérifié ses autorisations.

Un téléversement terminé signifie-t-il que le traitement des médias est terminé ?

Non. La fin du téléversement signifie que les octets du fichier sont parvenus au service. Le redimensionnement, l’encodage, l’analyse, l’export, l’approbation par l’application et la publication dans le catalogue peuvent encore être en attente et devraient avoir des états distincts.

Un téléversement devrait-il continuer lorsque la route Angular change ?

C’est une décision produit. Un outil de téléversement géré par un composant peut annuler le transfert lors de la destruction du composant, tandis qu’un service dont la durée de vie est plus longue peut maintenir l’opération lors des changements de route. Désignez un seul responsable et expliquez ce comportement à l’utilisateur.

Comment l’interface peut-elle reprendre après une actualisation ?

Enregistrez durablement l’identifiant de l’opération de l’application et l’identifiant de l’Assembly Transloadit sur le backend. Après l’actualisation, chargez l’état de référence de l’opération depuis la base de données de l’application et reliez-le aux éventuelles informations de reprise du transfert encore disponibles localement.

Pourquoi utiliser un webhook si Uppy peut attendre la fin de l’encodage ?

Un webhook permet au traitement de continuer après la fermeture du navigateur ou lorsque l’utilisateur quitte la page. Il fournit aussi au backend un point de réception de confiance permettant de nouvelles tentatives pour vérifier la fin du traitement et mettre à jour les enregistrements du catalogue lors d’opérations plus longues.