SDK Flutter beta da Transloadit: suporte a apps multiplataforma

Em setembro de 2022, demos as boas-vindas a um SDK da Transloadit para o framework de desenvolvimento multiplataforma Flutter. A versão 0.2.0 oferecia wrappers para operações da API da Transloadit e uploads de arquivos retomáveis usando o protocolo tus. Nós o lançamos como beta, convidamos os usuários a testá-lo e relatar bugs, e não o considerávamos pronto para produção.

O pacote está listado no pub.dev⁠.

Atualização de segurança, setembro de 2026: o exemplo original colocava um Auth Secret no cliente Flutter. Não distribua esse segredo em um app mobile, desktop ou web, nem o carregue no app a partir de configuração remota. O passo a passo executável foi substituído pelo fluxo histórico e pelas limitações específicas do pacote descritas abaixo. Manter o segredo em um backend confiável é obrigatório; disfarçá-lo em um app não o torna privado.

Instalação

A versão discutida aqui era 0.2.0. O registro de pacotes lista 0.2.1 como a versão publicada mais recente no momento desta atualização; o registro não contém a versão 1.0.0 mostrada anteriormente no exemplo de dependência deste artigo. O pacote 0.2.1 publicado declara a restrição de SDK do Dart >=2.12.0 <3.0.0 e uma dependência do SDK do Flutter. Ele não pode ser adicionado sem alterações a um projeto que usa Dart 3.

O caminho de importação da biblioteca é package:transloadit/transloadit.dart. Esses detalhes identificam o pacote histórico; não são uma recomendação para fazer downgrade de um projeto Flutter atual. Consulte os metadados publicados do pacote⁠ ao investigar uma integração existente.

Como usar o SDK

A classe de cliente publicada é TransloaditClient, e não a classe Transloadit usada no exemplo original. O cliente agrupa operações como criar Assemblies, consultar o status delas e gerenciar Templates, para que quem o chama não precise montar cada requisição HTTP manualmente.

No entanto, o construtor da versão 0.2.1 exige um authSecret, e sua implementação de requisições assina os parâmetros localmente. Ele não oferece nenhum callback público para assinaturas geradas no servidor. Simplesmente remover o segredo do construtor, passar uma string vazia ou adicionar uma URL de backend não transforma este pacote em uma integração segura de assinatura para mobile. Essa limitação também se aplica ao fluxo 0.2.0 descrito no anúncio.

Uma integração em produção precisa de outro caminho de requisição: seu backend deve autenticar o usuário, autorizar o upload e controlar as instruções de processamento, os destinos, os limites e a expiração. Ele pode criar a Assembly por conta própria ou fornecer parâmetros aprovados e de curta duração, junto com uma assinatura, a um cliente capaz de enviá-los sem alterações. Consulte nosso guia de Signature Authentication e a API de criação de Assemblies para esse protocolo. Trata-se de uma alternativa de arquitetura, não de um recurso fornecido por este pacote Flutter.

Como criar uma Assembly

O passo a passo original redimensionava uma imagem local para 400 pixels de largura. Sua sequência continua útil para entender como o SDK era organizado:

1. Chame o método newAssembly do cliente para obter um TransloaditAssembly. Esse objeto reúne os arquivos e os Steps antes de a requisição ser enviada.
2. Anexe a imagem de exemplo, cat.jpg, com addFile. O pacote publicado aceita um File e envolve o caminho dele em um XFile para o cliente tus.
3. Adicione um Step chamado resize, usando o Robot /image/resize com o parâmetro width definido como 400. Essa é a instrução de processamento da imagem, separada da transferência de seus bytes.
4. Envie com createAssembly. Primeiro, o pacote cria a Assembly e usa a URL de upload tus dela para transferir os arquivos.
5. Use onProgress para o progresso da transferência e onComplete para um upload de arquivo concluído. Nesse fluxo, a conclusão do upload é separada da conclusão do processamento; um callback de upload, por si só, não comprova que a imagem redimensionada esteja pronta.
6. Leia o TransloaditResponse retornado por meio de response.data['ok'], em vez de indexar o próprio objeto de resposta. ASSEMBLY_COMPLETED indica processamento bem-sucedido. O pacote também pode retornar uma Assembly cancelada ou abortada, e os erros precisam de tratamento próprio.

Esses detalhes da API explicam o fluxo do beta sem apresentar o caminho inseguro de assinatura no lado do cliente como uma receita atual de upload. Uma substituição deve preservar a distinção entre o progresso da transferência e os resultados do processamento, mantendo a autorização e os segredos no backend.

O que vem a seguir?

O anúncio originalmente indicava nossa série sobre um app de receitas em Flutter como um exemplo mais completo. Esse passo a passo histórico também distribuía credenciais por meio de configuração remota, então não deve ser seguido como guia de implementação segura. Ao projetar uma nova integração, comece pelas referências de autenticação e de Assembly citadas acima.

Para conhecer o histórico de implementação do beta e o rastreador de issues, visite o repositório do SDK Flutter⁠. O convite para contribuir continua de pé: uma integração de cliente que aceite parâmetros autorizados gerados no servidor precisaria de implementação e verificação próprias antes que pudéssemos recomendá-la aqui.