Subidas multimedia para aplicaciones de comercio en Angular

Conclusiones clave

Crea parámetros de subida firmados en el backend y acótalos a un Template aprobado.
Mantén explícita la propiedad del ciclo de vida de Uppy para que los cambios de ruta no filtren suscripciones ni dupliquen subidas.
Representa la subida y el procesamiento como estados de progreso separados.

Las aplicaciones de comercio suelen necesitar subidas de contenido multimedia de comerciantes, proveedores o clientes. El frontend debería ofrecer una selección y un progreso accesibles, mientras que los secretos, la política de validación, el procesamiento y el almacenamiento permanecen bajo control del servidor.

Define el límite de la subida antes de elegir los componentes

Una aplicación de comercio en Angular puede aceptar imágenes de comerciantes, proveedores, revisores o clientes, pero cada flujo de trabajo tiene permisos y consecuencias de publicación distintos. Define quién puede subir archivos, qué objeto del catálogo puede modificar, qué contenido multimedia se acepta, los límites, los derivados obligatorios, las reglas de aprobación y el almacenamiento final antes de construir el selector de archivos. El navegador debería recopilar los archivos y mostrar el estado. Un backend de confianza debería autorizar la acción, firmar los parámetros de procesamiento y decidir si el contenido multimedia finalizado pasa a formar parte del catálogo.

La transferencia directa del navegador al servicio de subida mantiene los cuerpos de archivo grandes lejos del servidor de la aplicación Angular, lo que reduce el ancho de banda y la duración de las solicitudes de la aplicación. Eso no saca al backend del modelo de seguridad. El backend sigue asociando la solicitud con un usuario autenticado y un producto, emite parámetros aprobados de corta duración, recibe información de finalización confiable y actualiza el registro de comercio. En este diseño, Transloadit se encarga de la recepción y el procesamiento de los archivos, no del renderizado de Angular, la lógica del catálogo, los carritos, el pago ni el inventario.

Navegador

Selecciona archivos, ofrece retroalimentación local, transfiere bytes y presenta los estados de subida y de procesamiento.

Backend de la aplicación

Autentica a los usuarios, autoriza productos, firma solicitudes, verifica la finalización y escribe el estado del catálogo.

Servicio de procesamiento

Valida y transforma el contenido multimedia aceptado según el flujo de trabajo aprobado.

Almacenamiento persistente

Guarda las salidas publicables que la tienda online o una capa de entrega independiente pueden servir.

Modela el trabajo de subida como una máquina de estados recuperable

Usa estados explícitos como inactivo, seleccionando, validando, esperando autorización, subiendo, pausado, procesando, completado, fallido y cancelado. Guarda un identificador de operación local estable y, una vez creada, el ID de la Assembly. El progreso de la transferencia de red y el progreso del procesamiento en el servidor son señales distintas y no deberían compartir un mismo porcentaje engañoso. Un archivo puede estar subido por completo mientras el redimensionamiento o la codificación de video siguen en curso.

Decide qué capa es propietaria de una subida activa cuando se destruye el componente. Un componente ligado a una ruta puede cancelarla y liberarla al navegar, mientras que un servicio de subidas de mayor duración puede conservar el trabajo entre rutas de forma intencionada. Cualquiera de las dos opciones puede ser válida, pero una propiedad accidental provoca suscripciones filtradas, manejadores de eventos duplicados o subidas que continúan sin controles visibles. Expón un estado de vista inmutable mediante signals de Angular o flujos de RxJS y centraliza las transiciones en lugar de dejar que varios callbacks de eventos modifiquen banderas no relacionadas.

Estado de la transferencia

Representa los bytes enviados, la pausa, la reanudación, la cancelación y los errores de red.

Estado del procesamiento

Representa el trabajo asíncrono del servidor una vez que han llegado suficientes datos de entrada.

Estado de la publicación

Representa la aprobación de la aplicación y la asociación con el catálogo, que pueden ocurrir después de que el procesamiento termina con éxito.

Emite parámetros de Assembly firmados y restringidos

Nunca coloques el Auth Secret de Transloadit en el código fuente de Angular, en la configuración de tiempo de ejecución que se entrega al navegador ni en un bundle generado. El backend debería verificar la sesión del usuario y su permiso sobre el producto de destino, construir parámetros de Assembly aprobados con una expiración cercana y un nonce único, firmar exactamente la carga útil serializada y devolver los parámetros junto con la firma. El navegador puede enviarlos, pero no puede cambiar un campo protegido sin invalidar la firma.

Usa un Template guardado para el flujo de trabajo estructural y establece allow_steps_override en false cuando los usuarios del navegador no deban alterar sus Steps. La solicitud firmada aún puede llevar campos acotados, como un identificador de producto o una elección de variante aprobada. Valida esos valores antes de firmar y de nuevo antes de usar los resultados. Guarda las credenciales de almacenamiento en credenciales de Template con los permisos mínimos necesarios en lugar de enviarlas al cliente. Una Auth Key identifica el workspace, pero son el secreto y el proceso de firma los que protegen la integridad de la solicitud.

Autenticar

Exige una identidad válida en la aplicación antes de generar la autorización de subida.

Autorizar

Confirma que esa identidad puede añadir contenido multimedia al comerciante, producto o pedido solicitado.

Limitar

Elige en el servidor el Template, la política de archivos, los límites, el alcance del destino, la expiración y los campos aprobados.

Auditar

Deja constancia del usuario, el producto, el nonce y el ID de la Assembly resultante sin registrar secretos ni cargas útiles firmadas completas.

Integra Uppy mediante un ciclo de vida gestionado por Angular

Uppy puede aportar la selección, el progreso y el comportamiento de subida reanudable, mientras que su plugin de Transloadit crea y sigue una Assembly. Crea la instancia de Uppy solo en un entorno de navegador, porque el renderizado en servidor de Angular no proporciona el objeto window ni el DOM, aunque el entorno de ejecución de Node.js sí ofrezca los globales File y Blob que pueden hacer que pasen comprobaciones de entorno ingenuas. Evita construirla durante la evaluación del módulo o en una ruta de componente renderizada en el servidor. Monta su interfaz después de que exista el destino y traduce sus eventos a estado de la aplicación en lugar de tratar el DOM interno del cliente de subida como fuente de verdad.

Instancia un único cliente de subida para el ámbito de propiedad previsto, registra cada detector de eventos una sola vez y elimina los detectores y los montajes de interfaz durante un desmontaje deliberado. Si un servicio singleton posee las subidas activas, expón una interfaz reducida a los componentes y conserva el estado por operación. Si el componente posee la instancia, destrúyela cuando termine la ruta e informa al usuario de que navegar cancela el trabajo. No crees una instancia nueva en cada ciclo de detección de cambios ni en cada suscripción, porque las instancias duplicadas pueden enviar los mismos archivos e informar de progresos contradictorios.

Comprobación de navegador

Inicializa el código de subida solo después de confirmar que el componente se ejecuta en el navegador.

Un único propietario

Asigna a un único componente o servicio la responsabilidad de crear la instancia, registrar los eventos y desmontarla.

Adaptador de estado

Convierte los eventos del cliente de subida en estados tipados de la aplicación que las plantillas puedan renderizar y probar.

Usa la reanudación sin prometer una recuperación imposible

El protocolo tus crea un recurso de subida, envía los bytes del archivo con peticiones que tienen en cuenta el offset y puede consultar al servidor el último offset aceptado tras una interrupción. Así se evita reiniciar una subida grande solo porque se haya caído la conexión. La capacidad de reanudar no equivale a una recuperación automática ante cualquier evento del navegador o de las rutas. La aplicación debe conservar la URL de subida y suficiente contexto local del archivo, y las políticas de privacidad o de almacenamiento del navegador aún pueden impedir la restauración.

Define el comportamiento de reintento y de cancelación para cada clase de fallo. Un error temporal de red puede esperar y reanudarse, una firma caducada puede requerir una nueva autorización del backend y un rechazo de validación del lado del servidor requiere un archivo corregido. Aplica una espera progresiva y un límite de intentos en lugar de reintentar indefinidamente una carga útil no válida. Cuando varios archivos comparten una operación, decide si un solo rechazo hace fallar todo el envío del producto o si los archivos válidos pueden continuar. Refleja esa política tanto en el Template como en la interfaz de usuario.

Pausar

Conserva la operación actual y muestra que no se están transfiriendo bytes.

Reanudar

Verifica el offset aceptado y continúa la transferencia restante cuando la autorización siga siendo válida.

Reintentar

Crea un nuevo intento controlado solo para los errores que la aplicación clasifique como recuperables.

Cancelar

Detén el trabajo de forma intencionada y deja claro el comportamiento resultante del catálogo y de los archivos temporales.

Crea una experiencia de subida accesible

El arrastrar y soltar debería complementar un campo de archivo etiquetado o un botón, no reemplazarlo. Cada acción necesita un control manejable con el teclado y un estado de foco visible. Explica los formatos aceptados, la cantidad y los límites de tamaño antes de la selección. Asocia los errores con el archivo correspondiente, ofrece un resumen de errores para los envíos de varios archivos y evita comunicar el fallo solo mediante el color. Una vista previa necesita un texto alternativo útil o un tratamiento decorativo claro según su propósito.

Anuncia los cambios de estado importantes mediante una región activa adecuada, sin narrar cada byte. Los usuarios suelen necesitar saber que la subida comenzó, se pausó, falló, se reanudó, entró en procesamiento y terminó. Mantén el porcentaje visible como texto y expón un valor de progreso accesible. La cancelación debería pedir confirmación cuando descarte una cantidad importante de trabajo. Si el procesamiento continúa después de navegar, ofrece un destino de estado persistente para que el usuario no tenga que mantener abierto el componente original.

Antes de la selección

Indica los archivos multimedia permitidos, los límites, el procesamiento previsto y si la publicación requiere revisión.

Durante la transferencia

Ofrece progreso por archivo, controles de pausa o cancelación y errores de red accionables.

Después de la transferencia

Distingue el procesamiento y la aprobación de la finalización de la subida, y ofrece una forma de volver al estado.

Completa el trabajo mediante una ruta asíncrona de confianza

Para operaciones de imagen breves, el navegador puede esperar a la codificación y usar el estado de la Assembly completada. Los flujos de trabajo de comercio más largos suelen beneficiarse de configurar el cliente para que no espere y de definir un notify_url. Transloadit envía el estado final de la Assembly a ese endpoint del backend cuando termina el procesamiento. El manejador debería verificar la firma del webhook con el secreto asociado a la Auth Key de la Assembly, rechazar las cargas útiles no válidas y confirmar con prontitud las notificaciones válidas. Las respuestas sin éxito pueden provocar reintentos de notificación, por lo que el manejador debe ser idempotente.

Guarda de forma persistente el ID de la Assembly cuando comience la operación y correlaciónalo con el usuario y el producto. Al finalizar, empareja los resultados con las subidas mediante identificadores como original_id, no por la posición en el array, porque el orden de los resultados no es un contrato de relación. Registra las URL exportadas persistentes y los metadatos necesarios, y después haz avanzar el registro multimedia del producto. No publiques URL temporales de procesamiento a los clientes. Si el navegador se pierde el evento de finalización, debería recuperar el estado desde la base de datos de la aplicación en lugar de convertirse en la única autoridad.

Verificar

Autentica la carga útil de finalización antes de aceptar su estado o sus URL.

Deduplicar

Trata las notificaciones repetidas para la misma Assembly y el mismo estado terminal como la misma operación.

Correlacionar

Resuelve el ID de la Assembly almacenado a un registro autorizado de la aplicación antes de escribir los resultados.

Publicar

Actualiza el catálogo solo después de que las salidas requeridas y cualquier comprobación de aprobación hayan tenido éxito.

Prueba la política, el ciclo de vida y las operaciones

Haz pruebas unitarias del adaptador de estado con secuencias de eventos de éxito, pausa, reintento, rechazo, cancelación, destrucción del componente y finalización duplicada. Prueba el endpoint de firma con usuarios no autenticados, productos no autorizados, campos inválidos, parámetros caducados y nonces repetidos. Las pruebas de navegador deberían usar controles accesibles para seleccionar los casos de prueba y deberían cubrir transferencias lentas, navegación, recarga, renderizado en servidor y un webhook que llega después de que el usuario se marche.

En el entorno de staging, sube archivos mal etiquetados, lotes demasiado grandes, imágenes demasiado pequeñas, contenedores corruptos y contenido multimedia que provoque un procesamiento largo. Confirma que la validación en el cliente ofrece una orientación rápida mientras que la validación en el servidor sigue siendo la definitiva. Supervisa los fallos de autorización, las transferencias abandonadas, la duración del procesamiento, los reintentos de webhook, los errores de destino y el costo por flujo de trabajo. Alerta sobre colas o fallos sostenidos, no sobre cada cancelación de un usuario. Conserva los identificadores saneados y las clases de error el tiempo suficiente para investigar sin almacenar datos personales innecesarios.

Pruebas de contrato

Verifica la forma de la respuesta del backend que esperan la integración de Uppy y el manejador de webhooks.

Pruebas de ciclo de vida

Demuestra que los cambios de ruta ni filtran un cliente de subida ni cancelan inesperadamente una operación propiedad de un servicio.

Simulacros de fallos

Pon a prueba las caídas del almacenamiento, las notificaciones duplicadas y la autorización caducada antes de que lo haga el tráfico de producción.

Detalles técnicos que conviene conocer

La transferencia directa del navegador al servicio de subida mantiene los bytes de los archivos fuera de los servidores de aplicaciones Angular, pero la firma de solicitudes y las decisiones de permisos deben permanecer en un backend de confianza.
RxJS puede modelar el progreso, la cancelación, los reintentos y el desmontaje de componentes, mientras que el protocolo de subida reanudable debe conservar suficiente estado para continuar después de una navegación o de una interrupción.
El renderizado en servidor de Angular no tiene objeto window ni DOM, aunque Node.js proporciona los globales File y Blob. La inicialización de la subida corresponde detrás de límites exclusivos del navegador, en lugar de ejecutarse durante el renderizado en servidor.
La reanudabilidad divide un archivo en transferencias recuperables, pero el progreso de la aplicación debería distinguir el preprocesamiento local, la subida por red y el procesamiento multimedia del lado del servidor.
Los cambios de ruta y la destrucción de componentes no deberían dejar huérfanas de forma silenciosa las subidas activas, salvo que el producto transfiera deliberadamente la propiedad a un servicio de mayor duración.
Los campos de selección de archivos necesitan etiquetas visibles, acceso por teclado, resúmenes de errores y anuncios de progreso, además de la interacción de arrastrar y soltar.

Un enfoque práctico

1
Define los campos multimedia, los límites, los derivados y las rutas de almacenamiento para un flujo de trabajo de producto.
2
Expón un endpoint de backend que devuelva parámetros de Assembly firmados y de corta duración.
3
Monta una sola instancia de Uppy, traduce sus eventos a estado de la aplicación y libérala de forma deliberada.
4
Consume el webhook de finalización en el servidor y actualiza el estado del producto a partir de un registro confiable.

Un flujo de trabajo multimedia de cuatro etapas

Cuándo resulta útil Transloadit

Integra Uppy en un componente de Angular o en un límite neutral respecto al framework, obtén parámetros de Assembly firmados desde el backend y muestra el progreso mientras Transloadit crea los derivados del producto y los exporta.

Límite de la arquitectura

Angular aporta los componentes de la tienda y la gestión del estado. Transloadit se encarga de la recepción y el procesamiento de archivos, no del carrito, el catálogo, el proceso de pago, el framework de renderizado ni el backend de comercio.

Preguntas frecuentes

¿Puede una aplicación Angular generar la firma de Transloadit en el navegador?

No. La generación de la firma requiere la Auth Secret, que debe permanecer en un backend de confianza. Angular debería solicitar parámetros firmados de corta duración después de que el backend autentique y autorice al usuario.

¿Una subida completada es lo mismo que un procesamiento multimedia completado?

No. Que la subida se complete significa que los bytes del archivo llegaron al servicio. El redimensionado, la codificación, el análisis, la exportación, la aprobación en la aplicación y la publicación en el catálogo pueden seguir pendientes y deberían tener estados independientes.

¿Debería continuar una subida cuando cambia la ruta de Angular?

Es una decisión de producto. Un cargador de archivos que pertenece a un componente puede cancelar durante su destrucción, mientras que un servicio de mayor duración puede conservar la operación entre rutas. Define un único propietario y comunica ese comportamiento al usuario.

¿Cómo puede recuperarse la interfaz tras una recarga?

Conserva en el backend el ID de operación de la aplicación y el ID de la Assembly de Transloadit. Tras la recarga, carga el estado de operación confiable desde la base de datos de la aplicación y vuelve a conectarlo con cualquier información de transferencia reanudable que siga disponible localmente.

¿Por qué usar un webhook si Uppy puede esperar a la codificación?

Un webhook permite que el procesamiento continúe después de que el navegador se cierra o navega a otra parte. Además, le da al backend un lugar confiable y reintentable para verificar la finalización y actualizar los registros del catálogo en operaciones de mayor duración.