Principais pontos
- Crie parâmetros de upload assinados no backend e restrinja-os a um Template aprovado.
- Mantenha explícita a responsabilidade pelo ciclo de vida do Uppy para que mudanças de rota não causem vazamento de inscrições nem uploads duplicados.
- Represente o upload e o processamento como estados de progresso separados.
Aplicações de comércio eletrônico frequentemente precisam receber uploads de mídia de lojistas, fornecedores ou clientes. O frontend deve oferecer seleção e progresso acessíveis, enquanto segredos, política de validação, processamento e armazenamento permanecem sob controle do servidor.
O que mais importa
- Persista o ID da Assembly para que a interface possa se recuperar após uma navegação ou uma atualização da página.
Defina a fronteira de responsabilidades do upload antes de escolher componentes
Uma aplicação de comércio eletrônico em Angular pode aceitar imagens de lojistas, fornecedores, avaliadores ou clientes, mas cada fluxo de trabalho tem permissões e consequências de publicação diferentes. Antes de construir o seletor, defina quem pode fazer upload, qual objeto do catálogo cada pessoa pode alterar, as mídias aceitas, os limites, os derivados exigidos, as regras de aprovação e o armazenamento final. O navegador deve coletar os arquivos e exibir o estado. Um backend confiável deve autorizar a ação, assinar os parâmetros de processamento e decidir se a mídia concluída passa a fazer parte do catálogo.
A transferência direta do navegador para o serviço de upload mantém corpos de arquivos grandes longe do servidor da aplicação Angular, o que reduz o consumo de banda da aplicação e a duração das requisições. Isso não retira o backend do modelo de segurança. O backend continua associando a requisição a um usuário autenticado e a um produto, emitindo parâmetros aprovados de curta duração, recebendo informações confiáveis de conclusão e atualizando o registro de comércio. Nesse design, a Transloadit cuida do recebimento e do processamento de arquivos, e não da renderização do Angular, da lógica do catálogo, dos carrinhos, do checkout nem do estoque.
Navegador
Seleciona arquivos, oferece feedback local, transfere bytes e apresenta os estados de upload e de processamento.
Backend da aplicação
Autentica usuários, autoriza produtos, assina requisições, verifica a conclusão e grava o estado do catálogo.
Serviço de processamento
Valida e transforma as mídias aceitas de acordo com o fluxo de trabalho aprovado.
Armazenamento persistente
Armazena as saídas publicáveis que a loja virtual ou uma camada de entrega separada pode servir.
Modele o trabalho de upload como uma máquina de estados recuperável
Use estados explícitos, como ocioso, selecionando, validando, aguardando autorização, fazendo upload, pausado, processando, concluído, com falha e cancelado. Armazene um identificador de operação local estável e, depois que a Assembly for criada, o ID da Assembly. O progresso da transferência pela rede e o progresso do processamento no servidor são sinais diferentes e não devem compartilhar uma única porcentagem enganosa. O upload de um arquivo pode estar totalmente concluído enquanto o redimensionamento ou a codificação de vídeo ainda está em execução.
Decida qual camada é responsável por um upload ativo quando o componente é destruído. Um componente específico de uma rota pode cancelá-lo e descartá-lo durante a navegação, enquanto um serviço de upload de vida mais longa pode preservar intencionalmente o trabalho entre rotas. Qualquer uma das escolhas pode ser válida, mas uma responsabilidade definida por acidente causa vazamento de inscrições, manipuladores de eventos duplicados ou uploads que continuam sem controles visíveis. Exponha um estado de visualização imutável por meio de signals do Angular ou streams do RxJS e centralize as transições, em vez de deixar que vários callbacks de eventos alterem flags não relacionadas.
Estado da transferência
Representa os bytes enviados, a pausa, a retomada, o cancelamento e os erros de rede.
Estado do processamento
Representa o trabalho assíncrono no servidor depois que dados de entrada suficientes chegaram.
Estado da publicação
Representa a aprovação pela aplicação e a associação ao catálogo, que podem ocorrer depois que o processamento é bem-sucedido.
Emita parâmetros de Assembly assinados e restritos
Nunca coloque o Auth Secret da Transloadit no código-fonte Angular, na configuração de runtime entregue ao navegador nem em um bundle gerado. O backend deve verificar a sessão do usuário e a permissão dele para o produto de destino, montar parâmetros de Assembly aprovados com uma expiração em futuro próximo e um nonce exclusivo, assinar exatamente o payload serializado e retornar os parâmetros junto com a assinatura. O navegador pode enviá-los, mas não consegue alterar um campo protegido sem invalidar a assinatura.
Use um Template salvo para o fluxo de trabalho estrutural e defina allow_steps_override como false quando os usuários do navegador não puderem alterar os Steps dele. A requisição assinada ainda pode levar campos delimitados, como um identificador de produto ou uma escolha de variante aprovada. Valide esses valores antes de assinar e novamente antes de usar os resultados. Mantenha as credenciais de armazenamento em Credenciais de Template, com as permissões mínimas necessárias, em vez de enviá-las ao cliente. Uma Auth Key identifica o Workspace, mas são o segredo e o processo de assinatura que protegem a integridade da requisição.
Autentique
Exija uma identidade de aplicação válida antes de gerar a autorização de upload.
Autorize
Confirme que a identidade pode adicionar mídia ao lojista, ao produto ou ao pedido solicitado.
Restrinja
Escolha no servidor o Template, a política de arquivos, os limites, o escopo de destino, a expiração e os campos aprovados.
Audite
Registre o usuário, o produto, o nonce e o Assembly ID resultante sem gravar segredos nem payloads assinados completos em log.
Integre o Uppy por meio de um ciclo de vida controlado pelo Angular
O Uppy pode oferecer seleção, progresso e upload retomável enquanto seu plugin da Transloadit cria e acompanha uma Assembly. Crie a instância do Uppy apenas em um ambiente de navegador, porque a renderização no servidor do Angular não fornece um objeto window nem um DOM, embora o runtime do Node.js forneça os globais File e Blob, que podem fazer verificações ingênuas de ambiente passarem. Evite construí-la durante a avaliação do módulo ou em um caminho de componente renderizado no servidor. Monte a interface dela depois que o elemento de destino existir e converta os eventos dela em estado da aplicação, em vez de tratar o DOM interno do uploader como fonte da verdade.
Instancie exatamente um uploader para o escopo de responsabilidade pretendido, registre cada listener uma única vez e remova os listeners e as montagens de interface durante a desmontagem deliberada. Se um serviço singleton for responsável pelos uploads ativos, exponha uma interface restrita aos componentes e preserve o estado de cada operação. Se o componente for responsável pela instância, destrua-a quando a rota terminar e avise o usuário de que a navegação cancela o trabalho. Não crie uma nova instância a cada ciclo de detecção de mudanças ou a cada inscrição, porque instâncias duplicadas podem enviar os mesmos arquivos e informar progressos conflitantes.
Verificação de navegador
Inicialize o código de upload somente depois de confirmar que o componente está sendo executado no navegador.
Responsável único
Atribua a um único componente ou serviço a responsabilidade pela criação da instância, pelo registro de eventos e pela desmontagem.
Adaptador de estado
Converta os eventos do uploader em estados tipados da aplicação que os templates possam renderizar e testar.
Use a retomada sem prometer uma recuperação impossível
O protocolo tus cria um recurso de upload, envia os bytes do arquivo com requisições que levam o offset em conta e pode consultar o servidor sobre o último offset aceito após uma interrupção. Isso evita reiniciar um upload grande só porque uma conexão caiu. Retomada não é o mesmo que recuperação automática de qualquer evento do navegador ou da rota. A aplicação precisa manter a URL de upload e contexto local suficiente sobre o arquivo, e as políticas de privacidade ou de armazenamento do navegador ainda podem impedir a restauração.
Defina o comportamento de nova tentativa e de cancelamento para cada classe de falha. Diante de um erro temporário de rede, é possível aguardar e retomar o upload; uma assinatura expirada pode exigir uma nova autorização do backend; e uma rejeição de validação no servidor exige um arquivo corrigido. Aplique backoff e um limite de tentativas em vez de repetir indefinidamente o envio de um payload inválido. Quando vários arquivos compartilham uma operação, decida se uma única rejeição faz falhar todo o envio do produto ou se os arquivos válidos podem continuar. Reflita essa política tanto no Template quanto na interface.
Pause
Mantenha a operação atual e mostre que nenhum byte está sendo transferido.
Retome
Verifique o offset aceito e continue a transferência restante quando a autorização ainda for válida.
Tente novamente
Crie uma nova tentativa controlada apenas para erros que a aplicação classifica como recuperáveis.
Cancele
Interrompa o trabalho intencionalmente e deixe claro o que acontece com o catálogo e com os arquivos temporários.
Crie uma experiência de upload acessível
O recurso de arrastar e soltar deve complementar um campo de arquivo com rótulo ou um botão com rótulo, e não substituir esse controle. Toda ação precisa de um controle operável pelo teclado e de um estado de foco visível. Explique os formatos aceitos e os limites de quantidade e tamanho antes da seleção. Associe os erros ao arquivo correspondente, forneça um resumo de erros para envios com vários arquivos e evite comunicar falhas apenas por cor. Uma prévia precisa de um texto alternativo útil ou de um tratamento decorativo claro, conforme a finalidade dela.
Anuncie mudanças de estado importantes por meio de uma região dinâmica (live region) adequada, sem narrar cada byte. Normalmente, os usuários precisam saber que o upload começou, foi pausado, falhou, foi retomado, entrou em processamento e foi concluído. Mantenha a porcentagem visível como texto e exponha um valor de progresso acessível. O cancelamento deve pedir confirmação quando descartar uma quantidade substancial de trabalho. Se o processamento continuar após a navegação, ofereça um destino de status persistente para que o usuário não precise manter o componente original aberto.
Antes da seleção
Informe as mídias permitidas, os limites, o processamento esperado e se a publicação exige revisão.
Durante a transferência
Ofereça progresso por arquivo, controles para pausar ou cancelar e erros de rede acionáveis.
Após a transferência
Diferencie o processamento e a aprovação da conclusão do upload e ofereça uma forma de voltar ao status.
Conclua o trabalho por um caminho assíncrono confiável
Para operações curtas com imagens, o navegador pode aguardar a codificação e usar o status da Assembly concluída. Fluxos de trabalho de comércio mais longos geralmente se beneficiam de configurar o cliente para não aguardar e de configurar notify_url. A Transloadit envia o status final da Assembly para esse endpoint do backend após o término do processamento. O handler deve verificar a assinatura do webhook com o segredo associado à Auth Key da Assembly, rejeitar payloads inválidos e confirmar prontamente as notificações válidas. Respostas sem sucesso podem provocar novas tentativas de notificação, por isso o handler precisa ser idempotente.
Persista o Assembly ID quando a operação começar e correlacione-o com o usuário e o produto. Na conclusão, associe os resultados aos uploads por meio de identificadores como original_id, e não pela posição no array, porque a ordem dos resultados não é um contrato de relacionamento. Registre as URLs exportadas persistentes e os metadados necessários e, em seguida, faça a transição do registro de mídia do produto. Não publique URLs temporárias de processamento para os clientes. Se o navegador perder o evento de conclusão, ele deve recuperar o status a partir do banco de dados da aplicação, em vez de se tornar a autoridade exclusiva.
Verifique
Autentique o payload de conclusão antes de aceitar o status ou as URLs que ele contém.
Elimine duplicatas
Trate notificações repetidas para a mesma Assembly e o mesmo estado terminal como a mesma operação.
Correlacione
Associe o Assembly ID armazenado a um registro autorizado da aplicação antes de gravar os resultados.
Publique
Atualize o catálogo somente depois que as saídas necessárias e quaisquer verificações de aprovação tiverem sido concluídas com sucesso.
Teste políticas, ciclo de vida e operações
Faça testes unitários do adaptador de estado com sequências de eventos de sucesso, pausa, nova tentativa, rejeição, cancelamento, destruição do componente e conclusão duplicada. Teste o endpoint de assinatura com usuários não autenticados, produtos não autorizados, campos inválidos, parâmetros expirados e nonces reenviados. Os testes de navegador devem usar controles acessíveis para selecionar arquivos de teste e devem cobrir transferência lenta, navegação, atualização da página, renderização no servidor e um webhook que chega depois que o usuário sai.
No ambiente de staging, faça upload de arquivos rotulados incorretamente, lotes grandes demais, imagens pequenas demais, contêineres corrompidos e mídias que disparam processamento longo. Confirme que a validação no cliente oferece orientação rápida, enquanto a validação no servidor continua sendo a autoridade. Monitore falhas de autorização, transferências abandonadas, duração do processamento, novas tentativas de webhook, erros de destino e custo por fluxo de trabalho. Crie alertas para filas ou falhas persistentes, não para cada cancelamento feito pelo usuário. Retenha identificadores sanitizados e classes de erro por tempo suficiente para investigar sem armazenar dados pessoais desnecessários.
Testes de contrato
Verifique o formato de resposta do backend esperado pela integração com o Uppy e pelo handler do webhook.
Testes de ciclo de vida
Comprove que mudanças de rota não deixam vazar um uploader nem cancelam inesperadamente uma operação pertencente a um serviço.
Simulações de falha
Simule indisponibilidade do armazenamento, notificações duplicadas e autorização expirada antes que o tráfego de produção o faça.
Detalhes técnicos que vale a pena conhecer
- A transferência direta do navegador para o serviço de upload mantém os bytes dos arquivos longe dos servidores da aplicação Angular, mas a assinatura de requisições e as decisões de permissão precisam permanecer em um backend confiável.
- O RxJS pode modelar progresso, cancelamento, novas tentativas e a desmontagem de componentes, enquanto o protocolo de upload retomável precisa reter estado suficiente para continuar após uma navegação ou interrupção.
- A renderização no servidor do Angular não tem objeto window nem DOM, embora o Node.js ofereça os globais File e Blob. A inicialização do upload deve ficar restrita a código executado apenas no navegador, e não ocorrer durante a renderização no servidor.
- A capacidade de retomada divide um arquivo em transferências recuperáveis, mas o progresso da aplicação deve distinguir pré-processamento local, upload pela rede e processamento de mídia no servidor.
- Mudanças de rota e a destruição de componentes não devem deixar uploads ativos órfãos silenciosamente, a menos que o produto transfira deliberadamente a responsabilidade para um serviço de vida mais longa.
- Campos de arquivo precisam de rótulos visíveis, acesso por teclado, resumos de erros e anúncios de progresso, além da interação de arrastar e soltar.
Uma abordagem prática
- 1
Defina os campos de mídia, os limites, os derivados e os caminhos de armazenamento para um fluxo de trabalho de produto.
- 2
Exponha um endpoint no backend que retorne parâmetros de Assembly assinados e de curta duração.
- 3
Monte uma única instância do Uppy, traduza os eventos dela em estado da aplicação e faça a limpeza dela de forma deliberada.
- 4
Consuma o webhook de conclusão no servidor e atualize o estado do produto a partir de um registro confiável.
Quando a Transloadit é útil
Incorpore o Uppy em um componente Angular ou em uma camada independente de framework, obtenha do backend parâmetros de Assembly assinados e exiba o progresso enquanto a Transloadit cria derivados de produto e os exporta.
Limite da arquitetura
O Angular fornece componentes de loja virtual e gerenciamento de estado. A Transloadit cuida do recebimento e do processamento de arquivos, não do carrinho, do catálogo, do checkout, do framework de renderização nem do backend de comércio.
Perguntas frequentes
Uma aplicação Angular pode gerar a assinatura da Transloadit no navegador?
Não. A geração da assinatura exige o Auth Secret, que deve permanecer em um backend confiável. O Angular deve solicitar parâmetros assinados de curta duração depois que o backend autenticar e autorizar o usuário.
Um upload concluído é o mesmo que um processamento de mídia concluído?
Não. A conclusão do upload significa que os bytes do arquivo chegaram ao serviço. Redimensionamento, codificação, análise, exportação, aprovação pela aplicação e publicação no catálogo ainda podem estar pendentes e devem ter estados separados.
Um upload deve continuar quando a rota do Angular muda?
Essa é uma decisão de produto. Um uploader pertencente ao componente pode cancelar a operação durante a desmontagem, enquanto um serviço de vida mais longa pode mantê-la entre rotas. Defina um único responsável e comunique o comportamento ao usuário.
Como a interface pode se recuperar após uma atualização da página?
Persista o ID da operação da aplicação e o ID da Assembly da Transloadit no backend. Após uma atualização da página, carregue o estado confiável da operação a partir do banco de dados da aplicação e reconecte-o a qualquer informação de transferência retomável que ainda esteja disponível localmente.
Por que usar um webhook se o Uppy pode aguardar a codificação?
Um webhook permite que o processamento continue depois que o navegador é fechado ou sai da página. Ele também oferece ao backend um ponto confiável e passível de novas tentativas para verificar a conclusão e atualizar os registros do catálogo em operações mais demoradas.