Wichtigste Erkenntnisse
- Erstellen Sie signierte Upload-Parameter im Backend und begrenzen Sie sie auf ein freigegebenes Template.
- Halten Sie die Zuständigkeit für den Uppy-Lebenszyklus explizit, damit Routenwechsel keine Subscriptions offen lassen und keine doppelten Uploads erzeugen.
- Stellen Sie Upload und Verarbeitung als getrennte Fortschrittszustände dar.
Commerce-Anwendungen benötigen häufig Medien-Uploads von Händlern, Lieferanten oder Kunden. Das Frontend sollte eine barrierefreie Auswahl und Fortschrittsanzeige bereitstellen, während Secrets, Validierungsrichtlinien, Verarbeitung und Speicherung serverseitig gesteuert bleiben.
Worauf es besonders ankommt
- Speichern Sie die Assembly ID dauerhaft, damit die UI nach Navigation oder Neuladen wiederhergestellt werden kann.
Die Upload-Grenze festlegen, bevor Komponenten ausgewählt werden
Eine Angular-Commerce-Anwendung kann Bilder von Händlern, Lieferanten, Prüfern oder Kunden annehmen, doch jeder Workflow hat andere Berechtigungen und andere Folgen für die Veröffentlichung. Legen Sie fest, wer hochladen darf, welches Katalogobjekt dabei geändert werden darf, welche Medien akzeptiert werden, welche Limits gelten, welche Derivate erforderlich sind, welche Freigaberegeln greifen und wo die endgültige Speicherung erfolgt, bevor Sie den Picker bauen. Der Browser sollte Dateien sammeln und den Zustand anzeigen. Ein vertrauenswürdiges Backend sollte die Aktion autorisieren, die Verarbeitungsparameter signieren und entscheiden, ob fertige Medien Teil des Katalogs werden.
Der direkte Transfer vom Browser zum Upload-Dienst hält große Dateiinhalte vom Angular-Anwendungsserver fern und reduziert so Bandbreite und Anfragedauer der Anwendung. Er nimmt das Backend jedoch nicht aus dem Sicherheitsmodell heraus. Das Backend verknüpft die Anfrage weiterhin mit einem authentifizierten Nutzer und einem Produkt, gibt kurzlebige, freigegebene Parameter aus, empfängt vertrauenswürdige Abschlussinformationen und aktualisiert den Commerce-Datensatz. Transloadit übernimmt in diesem Design die Dateiannahme und Verarbeitung, nicht das Angular-Rendering, die Katalog-Logik, Warenkörbe, Checkout oder Bestand.
Webbrowser
Wählt Dateien aus, liefert lokales Feedback, überträgt Bytes und stellt Upload- und Verarbeitungszustände dar.
Anwendungs-Backend
Authentifiziert Nutzer, autorisiert Produkte, signiert Anfragen, verifiziert den Abschluss und schreibt den Katalogzustand.
Verarbeitungsdienst
Validiert und transformiert akzeptierte Medien gemäß dem freigegebenen Workflow.
Persistenter Speicher
Hält veröffentlichungsfähige Ergebnisse vor, die die Storefront oder eine separate Auslieferungsschicht ausliefern kann.
Upload-Arbeit als wiederherstellbare Zustandsmaschine modellieren
Verwenden Sie explizite Zustände wie inaktiv, in Auswahl, in Validierung, wartend auf Autorisierung, im Upload, pausiert, in Verarbeitung, abgeschlossen, fehlgeschlagen und abgebrochen. Speichern Sie eine stabile lokale Vorgangskennung und, sobald sie erstellt wurde, die Assembly ID. Der Fortschritt der Netzwerkübertragung und der Fortschritt der serverseitigen Verarbeitung sind unterschiedliche Signale und sollten sich nicht einen einzigen irreführenden Prozentwert teilen. Eine Datei kann vollständig hochgeladen sein, während die Größenänderung oder das Video-Encoding noch läuft.
Entscheiden Sie, welche Schicht einen aktiven Upload besitzt, wenn die Komponente zerstört wird. Eine routenspezifische Komponente kann ihn bei der Navigation abbrechen und verwerfen, während ein länger lebender Upload-Service die Arbeit bewusst über Routen hinweg erhalten kann. Beide Entscheidungen können richtig sein, doch eine versehentliche Zuständigkeit führt zu offen gelassenen Subscriptions, doppelten Event-Handlern oder Uploads, die ohne sichtbare Steuerelemente weiterlaufen. Stellen Sie unveränderlichen View-Zustand über Angular Signals oder RxJS-Streams bereit und zentralisieren Sie die Übergänge, statt zuzulassen, dass mehrere Event-Callbacks voneinander unabhängige Flags verändern.
Übertragungszustand
Bildet gesendete Bytes, Pausieren, Fortsetzen, Abbruch und Netzwerkfehler ab.
Verarbeitungszustand
Bildet asynchrone Serverarbeit ab, nachdem genügend Eingabe eingetroffen ist.
Veröffentlichungszustand
Steht für die Freigabe durch die Anwendung und die Zuordnung zum Katalog, was nach erfolgreicher Verarbeitung erfolgen kann.
Signierte und eingeschränkte Assembly-Parameter ausstellen
Platzieren Sie das Transloadit Auth Secret niemals im Angular-Quellcode, in einer an den Browser ausgelieferten Laufzeitkonfiguration oder in einem generierten Bundle. Das Backend sollte die Sitzung des Nutzers und dessen Berechtigung für das betreffende Produkt prüfen, freigegebene Assembly-Parameter mit einem kurz in der Zukunft liegenden Ablaufzeitpunkt und einer eindeutigen Nonce erstellen, die exakt serialisierte Payload signieren und die Parameter samt Signatur zurückgeben. Der Browser kann sie übermitteln, aber er kann kein geschütztes Feld ändern, ohne die Signatur ungültig zu machen.
Verwenden Sie ein gespeichertes Template für den strukturellen Ablauf und setzen Sie allow_steps_override auf false, wenn Nutzer im Browser dessen Steps nicht verändern dürfen. Die signierte Anfrage kann weiterhin begrenzte Felder wie eine Produktkennung oder eine freigegebene Variantenauswahl enthalten. Prüfen Sie diese Werte vor dem Signieren und erneut, bevor Sie die Ergebnisse verwenden. Bewahren Sie Zugangsdaten für den Speicher in Template-Zugangsdaten mit den minimal nötigen Berechtigungen auf, statt sie an den Client zu senden. Ein Auth Key identifiziert den Workspace, doch die Integrität der Anfrage schützen das Secret und der Signierprozess.
Authentifizieren
Verlangen Sie eine gültige Identität in der Anwendung, bevor Sie eine Upload-Autorisierung erzeugen.
Autorisieren
Bestätigen Sie, dass diese Identität Medien zum angefragten Händler, zum angefragten Produkt oder zur angefragten Bestellung hinzufügen darf.
Einschränken
Wählen Sie Template, Dateirichtlinie, Limits, Zielbereich, Ablaufzeitpunkt und freigegebene Felder serverseitig aus.
Auditieren
Erfassen Sie Nutzer, Produkt, Nonce und die resultierende Assembly ID, ohne Secrets oder vollständige signierte Payloads zu protokollieren.
Uppy über einen von Angular verwalteten Lebenszyklus integrieren
Uppy kann Funktionen für Auswahl, Fortschritt und fortsetzbare Uploads bereitstellen, während sein Transloadit-Plugin eine Assembly erstellt und verfolgt. Erzeugen Sie die Uppy-Instanz ausschließlich in einer Browser-Umgebung, denn beim Server-Rendering von Angular gibt es weder ein DOM noch das Objekt window, auch wenn die Node.js-Laufzeit die globalen Objekte File und Blob bereitstellt, wodurch naive Umgebungsprüfungen erfolgreich sein können. Vermeiden Sie es, sie während der Modulauswertung oder in einem serverseitig gerenderten Komponentenpfad zu konstruieren. Binden Sie ihre UI erst ein, wenn das Zielelement existiert, und übersetzen Sie ihre Events in Anwendungszustand, statt das interne DOM des Dateiuploaders als Quelle der Wahrheit zu behandeln.
Instanziieren Sie genau einen Dateiuploader für den vorgesehenen Zuständigkeitsbereich. Registrieren Sie jeden Listener genau einmal und entfernen Sie Listener und UI-Einbindungen beim gezielten Teardown. Wenn der Singleton-Service die aktiven Uploads besitzt, halten Sie die Schnittstelle zu den Komponenten schmal und bewahren Sie den Zustand je Vorgang. Wenn die Komponente die Instanz besitzt, zerstören Sie sie am Ende der Route und weisen Sie die Nutzer darauf hin, dass das Navigieren die Arbeit abbricht. Erzeugen Sie die Instanz nicht bei jedem Durchlauf der Change Detection und nicht bei jedem Abonnement neu, denn doppelte Instanzen können dieselben Dateien übermitteln und widersprüchlichen Fortschritt melden.
Browser-Prüfung
Initialisieren Sie den Upload-Code erst, nachdem Sie bestätigt haben, dass die Komponente im Browser läuft.
Ein einziger Besitzer
Übertragen Sie einer einzigen Komponente oder einem Service die Verantwortung für Instanzerstellung, Event-Registrierung und Teardown.
Zustandsadapter
Wandeln Sie Events des Dateiuploaders in typisierte Anwendungszustände um, die Vorlagen rendern und testen können.
Fortsetzbarkeit nutzen, ohne unmögliche Wiederherstellung zu versprechen
Das tus-Protokoll erstellt eine Upload-Ressource, sendet Dateibytes mit Offset-bewussten Anfragen und kann nach einer Unterbrechung den zuletzt akzeptierten Offset beim Server abfragen. So muss ein großer Upload nicht allein deshalb neu gestartet werden, weil eine Verbindung abgebrochen ist. Fortsetzbarkeit ist nicht dasselbe wie eine automatische Wiederherstellung nach jedem Browser- oder Routing-Ereignis. Die Anwendung muss die Upload-URL und ausreichend lokalen Dateikontext vorhalten, und Datenschutz- oder Speicherrichtlinien des Browsers können eine Wiederherstellung dennoch verhindern.
Legen Sie für jede Fehlerklasse das Verhalten bei Retries und Abbrüchen fest. Bei einem vorübergehenden Netzwerkfehler kann gewartet und fortgesetzt werden, eine abgelaufene Signatur kann eine neue Autorisierung durch das Backend erfordern, und eine serverseitige Ablehnung durch die Validierung erfordert eine korrigierte Datei. Setzen Sie Backoff und ein Versuchslimit ein, statt eine ungültige Payload endlos erneut zu senden. Wenn mehrere Dateien zu einem Vorgang gehören, entscheiden Sie, ob eine einzelne Ablehnung die gesamte Produkteinreichung scheitern lässt oder ob gültige Dateien fortfahren dürfen. Bilden Sie diese Richtlinie sowohl im Template als auch in der UI ab.
Pausieren
Behalten Sie den aktuellen Vorgang bei und zeigen Sie, dass keine Bytes übertragen werden.
Fortsetzen
Prüfen Sie den akzeptierten Offset und setzen Sie die verbleibende Übertragung fort, wenn die Autorisierung noch gültig ist.
Erneut versuchen
Starten Sie nur bei Fehlern, die die Anwendung als behebbar einstuft, einen kontrollierten neuen Versuch.
Abbrechen
Beenden Sie die Arbeit bewusst und machen Sie deutlich, was daraus für den Katalog und für temporäre Dateien folgt.
Ein barrierefreies Upload-Erlebnis gestalten
Drag-and-drop sollte ein beschriftetes Dateifeld oder einen beschrifteten Button ergänzen, nicht ersetzen. Jede Aktion braucht ein per Tastatur bedienbares Bedienelement und einen sichtbaren Fokuszustand. Erläutern Sie akzeptierte Formate, Anzahl und Größenbeschränkungen vor der Auswahl. Ordnen Sie Fehler der jeweiligen Datei zu, stellen Sie bei Einreichungen mit mehreren Dateien eine Fehlerübersicht bereit und vermeiden Sie es, ein Scheitern allein über Farbe zu vermitteln. Eine Vorschau braucht je nach Zweck einen nützlichen Alternativtext oder eine eindeutig dekorative Behandlung.
Geben Sie wichtige Zustandsänderungen über eine passende Live-Region bekannt, ohne jedes Byte zu kommentieren. Nutzer müssen in der Regel wissen, dass ein Upload begonnen hat, pausiert wurde, fehlgeschlagen ist, fortgesetzt wurde, in die Verarbeitung übergegangen ist und abgeschlossen wurde. Halten Sie den Prozentwert als Text sichtbar und stellen Sie einen barrierefrei zugänglichen Fortschrittswert bereit. Ein Abbruch sollte eine Bestätigung verlangen, wenn dabei erhebliche Arbeit verworfen wird. Wenn die Verarbeitung nach einer Navigation weiterläuft, bieten Sie eine dauerhaft verfügbare Statusansicht an, damit Nutzer die ursprüngliche Komponente nicht geöffnet lassen müssen.
Vor der Auswahl
Nennen Sie erlaubte Medien, Limits, die zu erwartende Verarbeitung und ob die Veröffentlichung eine Prüfung erfordert.
Während der Übertragung
Bieten Sie dateibezogenen Fortschritt, Bedienelemente zum Pausieren oder Abbrechen und Netzwerkfehler mit konkreten Handlungshinweisen.
Nach der Übertragung
Unterscheiden Sie Verarbeitung und Freigabe vom Abschluss des Uploads und bieten Sie einen Weg zurück zur Statusansicht.
Arbeit über einen vertrauenswürdigen asynchronen Pfad abschließen
Bei kurzen Bildoperationen kann der Browser auf das Encoding warten und den abgeschlossenen Assembly Status verwenden. Längere Commerce-Workflows profitieren in der Regel davon, den Client so einzustellen, dass er nicht wartet, und eine notify_url zu konfigurieren. Transloadit sendet den finalen Assembly Status nach Ende der Verarbeitung an diesen Backend-Endpunkt. Der Handler sollte die Webhook-Signatur mit dem Secret prüfen, mit dem der Auth Key dieser Assembly verknüpft ist, ungültige Payloads ablehnen und gültige Benachrichtigungen zeitnah bestätigen. Antworten ohne Erfolgsstatus können Wiederholungen der Benachrichtigung auslösen, daher muss der Handler idempotent sein.
Speichern Sie die Assembly ID dauerhaft, sobald der Vorgang startet, und ordnen Sie sie dem Nutzer und dem Produkt zu. Ordnen Sie die Ergebnisse nach Abschluss über Identifikatoren wie original_id den Uploads zu, nicht über die Array-Position, denn die Reihenfolge der Ergebnisse ist keine zugesicherte Zuordnung. Erfassen Sie dauerhafte exportierte URLs und die erforderlichen Metadaten und überführen Sie anschließend den Datensatz der Produktmedien in den nächsten Zustand. Veröffentlichen Sie keine temporären Verarbeitungs-URLs gegenüber Kunden. Verpasst der Browser das Abschluss-Event, sollte er den Status aus der Datenbank der Anwendung wiederherstellen, statt selbst zur alleinigen Autorität zu werden.
Verifizieren
Authentifizieren Sie die Abschluss-Payload, bevor Sie deren Status oder URLs übernehmen.
Deduplizieren
Behandeln Sie wiederholte Benachrichtigungen für dieselbe Assembly und denselben Endzustand als denselben Vorgang.
Zuordnen
Lösen Sie die gespeicherte Assembly ID zu einem autorisierten Datensatz der Anwendung auf, bevor Sie Ergebnisse schreiben.
Veröffentlichen
Aktualisieren Sie den Katalog erst, wenn die erforderlichen Ausgaben und etwaige Freigabeprüfungen erfolgreich waren.
Richtlinien, Lebenszyklus und Betrieb testen
Testen Sie den Zustandsadapter per Unit-Test mit Ereignissequenzen für Erfolg, Pause, Wiederholung, Ablehnung, Abbruch, Zerstörung der Komponente und doppelten Abschluss. Testen Sie den Signatur-Endpunkt für nicht authentifizierte Nutzer, nicht autorisierte Produkte, ungültige Felder, abgelaufene Parameter und erneut gesendete Nonces. Browser-Tests sollten Fixtures über barrierefreie Bedienelemente auswählen und langsame Übertragung, Navigation, Neuladen, Server-Rendering sowie einen Webhook abdecken, der eintrifft, nachdem der Nutzer die Seite verlassen hat.
Laden Sie in der Staging-Umgebung falsch gekennzeichnete Dateien, zu große Batches, zu kleine Bilder, beschädigte Container und Medien hoch, die eine lange Verarbeitung auslösen. Stellen Sie sicher, dass die clientseitige Validierung schnelle Hinweise gibt, während die serverseitige Validierung maßgeblich bleibt. Überwachen Sie Autorisierungsfehler, abgebrochene Übertragungen, Verarbeitungsdauer, Webhook-Wiederholungen, Fehler am Zielsystem und Kosten pro Workflow. Alarmieren Sie bei anhaltenden Queues oder Fehlern, nicht bei jedem Abbruch durch Nutzer. Bewahren Sie bereinigte Identifikatoren und Fehlerklassen lange genug auf, um Vorfälle untersuchen zu können, ohne unnötige personenbezogene Daten zu speichern.
Schnittstellentests
Prüfen Sie die Struktur der Backend-Antwort, die die Uppy-Integration und der Webhook-Handler erwarten.
Lebenszyklus-Tests
Weisen Sie nach, dass Routenwechsel weder ein Uploader-Leck verursachen noch einen vom Service verwalteten Vorgang unerwartet abbrechen.
Ausfallübungen
Erproben Sie Speicherausfälle, doppelte Benachrichtigungen und abgelaufene Autorisierung, bevor es der Produktions-Traffic tut.
Wissenswerte technische Details
- Die direkte Übertragung vom Browser zum Upload-Dienst hält Datei-Bytes von den Angular-Anwendungsservern fern, doch Request-Signierung und Berechtigungsentscheidungen müssen auf einem vertrauenswürdigen Backend bleiben.
- RxJS kann Fortschritt, Abbruch, Retries und den Abbau von Komponenten abbilden, während das Protokoll für fortsetzbare Uploads genug Zustand vorhalten muss, um nach Navigation oder Unterbrechung fortzufahren.
- Beim Server-Rendering von Angular gibt es kein window-Objekt und kein DOM, auch wenn Node.js die Globals File und Blob bereitstellt. Die Initialisierung von Uploads gehört hinter rein browserseitige Grenzen und sollte nicht während des Server-Renderings ausgeführt werden.
- Fortsetzbarkeit teilt eine Datei in wiederherstellbare Übertragungen auf, doch der Fortschritt in der Anwendung sollte zwischen lokaler Vorverarbeitung, Netzwerk-Upload und serverseitiger Medienverarbeitung unterscheiden.
- Routenwechsel und das Zerstören von Komponenten sollten aktive Uploads nicht stillschweigend verwaisen lassen, es sei denn, das Produkt übergibt die Zuständigkeit bewusst an einen langlebigeren Dienst.
- Dateieingaben brauchen zusätzlich zur Drag-and-drop-Interaktion sichtbare Beschriftungen, Tastaturzugang, Fehlerzusammenfassungen und Fortschrittsansagen.
Ein praxisnaher Ansatz
- 1
Legen Sie die Medienfelder, Limits, Derivate und Speicherpfade für einen einzelnen Produkt-Workflow fest.
- 2
Stellen Sie einen Backend-Endpunkt bereit, der kurzlebige signierte Assembly-Parameter zurückgibt.
- 3
Binden Sie eine einzelne Uppy-Instanz ein, überführen Sie deren Ereignisse in den Anwendungszustand und räumen Sie sie gezielt wieder auf.
- 4
Verarbeiten Sie den Abschluss-Webhook serverseitig und aktualisieren Sie den Produktzustand aus einem vertrauenswürdigen Datensatz.
Wann Transloadit hilfreich ist
Binden Sie Uppy in eine Angular-Komponente oder eine framework-neutrale Grenzschicht ein, holen Sie signierte Assembly-Parameter vom Backend und zeigen Sie den Fortschritt an, während Transloadit Produkt-Derivate erstellt und exportiert.
Architekturgrenze
Angular stellt Storefront-Komponenten und State Management bereit. Transloadit übernimmt die Dateiannahme und Verarbeitung, nicht den Warenkorb, den Katalog, den Checkout, das Rendering-Framework oder das Commerce-Backend.
Häufig gestellte Fragen
Kann eine Angular-Anwendung die Transloadit-Signatur im Browser erzeugen?
Nein. Für die Signaturerzeugung ist das Auth Secret erforderlich, das auf einem vertrauenswürdigen Backend verbleiben muss. Angular sollte kurzlebige signierte Parameter anfordern, nachdem das Backend den Nutzer authentifiziert und autorisiert hat.
Ist ein abgeschlossener Upload dasselbe wie eine abgeschlossene Medienverarbeitung?
Nein. Ein abgeschlossener Upload bedeutet, dass die Datei-Bytes den Dienst erreicht haben. Größenänderung, Encoding, Analyse, Export, Freigabe in der Anwendung und Veröffentlichung im Katalog können weiterhin ausstehen und sollten eigene Zustände haben.
Soll ein Upload fortgesetzt werden, wenn sich die Angular-Route ändert?
Das ist eine Produktentscheidung. Ein Uploader, der einer Komponente gehört, kann beim Abbau der Komponente abbrechen, während ein länger lebender Service den Vorgang über Routen hinweg beibehalten kann. Legen Sie einen einzigen Eigentümer fest und kommunizieren Sie das Verhalten an die Nutzer.
Wie kann die UI nach einem Neuladen wiederhergestellt werden?
Speichern Sie die Vorgangs-ID der Anwendung und die Transloadit Assembly ID dauerhaft im Backend. Laden Sie nach einem Neuladen den vertrauenswürdigen Vorgangszustand aus der Anwendungsdatenbank und verbinden Sie ihn wieder mit allen fortsetzbaren Transferinformationen, die lokal noch verfügbar sind.
Warum einen Webhook verwenden, wenn Uppy auf das Encoding warten kann?
Ein Webhook ermöglicht es, dass die Verarbeitung weiterläuft, nachdem der Browser geschlossen wurde oder weggenavigiert ist. Außerdem erhält das Backend damit eine vertrauenswürdige Stelle, an der fehlgeschlagene Versuche wiederholt werden können, um den Abschluss zu verifizieren und Katalogeinträge bei länger laufenden Vorgängen zu aktualisieren.