Apresentamos nosso novo SDK para iOS e macOS: TransloaditKit

Mark Masterson

Desenvolvedor iOS e macOS · Los Angeles, Califórnia, EUA · Mostrar biografia

Em novembro de 2017, chegou mais um SDK novo: nosso SDK para iOS e macOS, o TransloaditKit! Escrita em Objective-C e utilizável tanto em Objective-C quanto em Swift, a versão 1.0.0 levou aos apps da Apple as funcionalidades básicas da Transloadit e uploads retomáveis usando o tus⁠. Planejávamos novas atualizações para ampliar a cobertura da API da Transloadit.

Atualização de segurança, setembro de 2026: este é o anúncio original do lançamento, com a configuração insegura de credenciais e os exemplos executáveis obsoletos já substituídos. Nunca coloque seu Auth Secret em Info.plist, em um binário do app ou em configurações baixadas pelo app. Mantenha-o em um servidor confiável. O servidor deve autenticar o usuário e autorizar o upload solicitado antes de aprovar qualquer assinatura. Nosso guia de Signature Authentication explica esse limite e como exigir assinaturas no seu Workspace.

No lançamento, o pacote do CocoaPods se chamava Transloadit. A integração com Swift também precisava da dependência Arcane para contornar os cabeçalhos originais. Esses detalhes de configuração pertencem ao lançamento em Objective-C; não são instruções para a implementação posterior em Swift. A versão 1.0.0 assinava as requisições dentro do SDK usando o segredo configurado nele e não expunha nenhum callback externo de assinatura. Mover esse segredo para outro arquivo de configuração do app não corrigiria o limite de segurança.

O lançamento posterior do TransloaditKit 3.5.0⁠ adicionou um inicializador signatureGenerator que permite manter o Auth Secret no seu servidor. Para essa versão, a declaração do CocoaPods é:

pod 'Transloadit', '3.5.0'

Quem usa o Swift Package Manager pode selecionar exatamente a mesma versão no repositório do TransloaditKit⁠. O helper em Swift a seguir usa a API pública dessa versão. Ele recebe a integração de assinatura já existente no backend do app; ele não implementa um serviço de assinatura:

import Foundation
import TransloaditKit

func makeUploadClient(
    authKey: String,
    configuration: URLSessionConfiguration = .default,
    signatureGenerator: @escaping SignatureGenerator
) -> Transloadit {
    Transloadit(
        apiKey: authKey,
        sessionConfiguration: configuration,
        signatureGenerator: signatureGenerator
    )
}

func makeResizeStep() -> Step {
    Step(
        name: "encode",
        robot: "/image/resize",
        options: ["width": 400, "result": true]
    )
}

A integração de assinatura recebe exatamente os parâmetros serializados. Seu backend deve permitir apenas as instruções de processamento, os destinos, os limites de arquivo e a expiração autorizados para esse usuário; rejeite instruções arbitrárias escolhidas pelo cliente. Assine os bytes aprovados sem serializá-los novamente. Retorne apenas a assinatura e conclua o callback do SDK com sucesso ou falha em todos os caminhos, inclusive em caso de timeout de rede.

Há uma limitação importante em 3.5.0: a criação da Assembly define auth.expires para 24 horas no futuro, e o callback público de assinatura não pode substituir esses parâmetros. Se a sua política exigir uma validade menor, esse caminho de criação não consegue atendê-la. Em vez disso, crie a Assembly no seu backend ou use a API de criação de Assemblies com parâmetros controlados pelo servidor. Não aceite silenciosamente uma expiração mais longa só para fazer o callback ter sucesso.

Um exemplo rápido de criação de uma Assembly

O exemplo original demonstrava uma Assembly de redimensionamento de imagens. Seu fluxo de trabalho tinha várias etapas distintas:

1. Crie um Assembly Step chamado encode usando o Robot /image/resize. O helper em Swift acima expressa essa operação com o inicializador posterior Step, adicionando uma largura de 400 pixels e solicitando um resultado.
2. Na API original em Objective-C, crie um Assembly com os Steps e a quantidade esperada de arquivos e, em seguida, anexe a URL do arquivo local. Os snippets originais em Swift usavam essa mesma API em Objective-C por meio da sua ponte para Swift.
3. Registre os callbacks de conclusão e de status antes de iniciar a requisição. O antigo assemblyCompletionBlock recebia a resposta de criação da Assembly, incluindo assembly_ssl_url. O exemplo atribuía essa URL antes de chamar invokeAssembly para iniciar o upload e checkAssembly para verificar o status do processamento.
4. Trate separadamente o progresso do upload, a conclusão do processamento e as falhas. Receber uma Assembly URL não significa que os arquivos da Assembly já terminaram o upload ou o processamento.

O SDK posterior em Swift usa createAssembly e um TransloaditPoller retornado para o fluxo combinado de upload e processamento. O callback de criação dele não é uma notificação de resultado final. Os helpers makeUploadClient e makeResizeStep acima demonstram apenas a configuração do cliente e a construção do Step; um app ainda precisa da sua integração autorizada com o backend, da seleção de arquivos, do ciclo de vida do upload e do tratamento dos resultados.

Essa separação é importante para uploads retomáveis: o tus pode retomar uma transferência após uma interrupção, enquanto a Assembly representa o fluxo de processamento em torno dela. Assim como no lançamento original, recebemos de bom grado contribuições que melhorem as duas partes da integração. Consulte o código-fonte e a documentação do SDK⁠ para ver as APIs da versão que você usa.