TransloaditKit

O TransloaditKit oferece upload e processamento de arquivos para aplicativos iOS e macOS. Este guia usa a API Swift do TransloaditKit 3.5.0, com o TUSKit 3.6.0 na configuração verificada abaixo. As versões anteriores em Objective-C têm APIs diferentes; consulte o anúncio original (English) para conhecer esse histórico de versões.

Instalar

CocoaPods

pod 'Transloadit', '3.5.0'
pod 'TUSKit', '3.6.0'

O intervalo de versões da dependência do pod é ~> 3.6.0 (no mínimo 3.6.0, abaixo de 3.7.0). Fixe a versão do TUSKit explicitamente para usar a versão verificada aqui e mantenha Podfile.lock junto ao seu projeto.

Swift Package Manager

Adicione https://github.com/transloadit/TransloaditKit nas configurações de pacotes do Xcode com a versão exata 3.5.0 e selecione o produto de biblioteca TransloaditKit. Essa versão fixa o TUSKit em 3.6.0. Mantenha as versões resolvidas das dependências junto ao seu projeto.

O CocoaPods expõe o módulo Transloadit; o Swift Package Manager expõe TransloaditKit. A importação condicional abaixo aceita ambas as instalações.

Uso

Nunca coloque o Auth Secret em um binário de aplicativo, em Info.plist ou em configurações baixadas pelo aplicativo, inclusive no caso de aplicativos internos. Mantenha-o no seu backend e exija Signature Authentication para o Workspace ou Template usado pelo aplicativo.

O inicializador apiKey:sessionConfiguration:signatureGenerator: aceita uma assinatura sem exigir o Auth Secret. O SDK fornece a string serializada exata de params para assinar. Seu backend deve autenticar a sessão do usuário e autorizar o upload solicitado, permitindo apenas a Auth Key, as instruções de processamento, os destinos e a expiração esperados. Rejeite Steps extras, Templates arbitrários, campos e opções desconhecidas. Um chamador autenticado não deve poder usar o backend para assinar JSON arbitrário. Aplique cotas e restrições de upload no servidor; para um Template de propriedade do servidor, desative allow_steps_override e permita apenas esse Template.

Há duas restrições nesta versão fixada:

A criação de uma Assembly fixa auth.expires em 24 horas no futuro. O callback de assinatura não pode substituir esses parâmetros. Se a política do seu servidor exigir um prazo de expiração mais curto, rejeite a solicitação e use a criação de Assemblies pelo backend ou outra integração com a API de Assemblies com parâmetros controlados pelo servidor. Não flexibilize sua política para acomodar o SDK.
O parâmetro SignatureCompletion não permite escape: chame-o antes que o gerador de assinaturas retorne. Um callback de conclusão HTTP assíncrono comum não pode capturá-lo. A função auxiliar abaixo aceita um transporte síncrono para o backend e deve ser usada fora da thread principal. Esse transporte deve ter um tempo limite finito e lançar um erro em caso de falha; o SDK não fornece tempo limite nem alternativa em caso de falha na assinatura.

Seu aplicativo fornece requestSignature, a integração HTTPS autenticada dele com seu próprio backend. Envie a string original de parâmetros sem alterações e o token da sessão atual do usuário no cabeçalho Authorization da solicitação, usando um endpoint fixo e confiável, rejeitando redirecionamentos e respostas HTTP sem sucesso. O token pertence ao sistema de login do seu aplicativo, não à Transloadit. O backend valida a solicitação e assina os bytes UTF-8 originais aprovados com HMAC-SHA384. Ele retorna a mesma string de parâmetros e uma assinatura, nunca o Auth Secret. Não serialize novamente nem altere a expiração após a aprovação. Quando a sessão expirar, renove-a antes de criar um novo cliente.

A função auxiliar completa abaixo verifica se o backend aprovou esses parâmetros exatos e forneceu uma assinatura bem formada. As verificações no cliente não substituem a autorização no backend. ApprovedSignature é o tipo de resposta deste exemplo, não um tipo do SDK.

import Foundation
#if canImport(TransloaditKit)
import TransloaditKit
#else
import Transloadit
#endif

struct ApprovedSignature {
    let params: String
    let signature: String
}

enum SigningError: Error {
    case missingSession
    case notApproved
}

func makeUploadClient(
    authKey: String,
    userSessionToken: String,
    configuration: URLSessionConfiguration = .default,
    requestSignature: @escaping (String, String) throws -> ApprovedSignature
) throws -> Transloadit {
    guard !userSessionToken.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
        throw SigningError.missingSession
    }
    return Transloadit(
        apiKey: authKey,
        sessionConfiguration: configuration,
        signatureGenerator: { params, completion in
            completion(Result {
                let approved = try requestSignature(params, userSessionToken)
                let signature = approved.signature
                guard approved.params.utf8.elementsEqual(params.utf8),
                      signature.hasPrefix("sha384:"), signature.count == 103,
                      signature.dropFirst(7).allSatisfy({ "0123456789abcdef".contains($0) }) else {
                    throw SigningError.notApproved
                }
                return signature
            })
        }
    )
}

Criar uma Assembly

Esta função auxiliar completa cria um Step de redimensionamento, coloca os arquivos locais fornecidos na fila de upload e registra um callback de status de processamento. Inclua-a junto à função auxiliar do cliente acima. A política do backend para este exemplo deve permitir exatamente este redimensionamento de 200 × 100 com fit e result: true. Neste SDK, a quantidade de arquivos para upload é transmitida fora dos parâmetros assinados, portanto não constitui um limite de autorização. Se as restrições de arquivo necessárias não puderem ser aplicadas pelo fluxo de trabalho selecionado, crie a Assembly pelo seu backend em vez de emitir uma assinatura mais abrangente.

func makeResizeStep() -> Step {
    Step(
        name: "resize",
        robot: "/image/resize",
        options: [
            "width": 200,
            "height": 100,
            "resize_strategy": "fit",
            "result": true
        ]
    )
}

@discardableResult
func uploadImages(
    client: Transloadit,
    files: [URL],
    created: @escaping (Result<Assembly, TransloaditError>) -> Void,
    status: @escaping (Result<AssemblyStatus, TransloaditError>) -> Void
) -> TransloaditPoller {
    let poller = client.createAssembly(
        steps: [makeResizeStep()], andUpload: files, completion: created
    )
    poller.pollAssemblyStatus(completion: status)
    return poller
}

Passe as URLs de arquivos locais com permissão de leitura, obtidas na seleção de arquivos do seu aplicativo, para uploadImages e mantenha uma referência ao cliente Transloadit durante a operação. Faça a chamada em uma fila em segundo plano, pois a assinatura é síncrona; encaminhe as atualizações da interface feitas nos callbacks para a fila principal. Trate falhas em ambos os callbacks. Um callback created bem-sucedido significa que a Assembly existe e que os uploads foram colocados na fila, não que o upload ou o processamento terminou. No callback de status, inspecione processingStatus: completed, aborted e canceled são resultados finais distintos.

Para acompanhar o progresso dos arquivos e os erros de upload, implemente e mantenha uma referência a um TransloaditFileDelegate e atribua-o à propriedade de referência fraca fileDelegate do cliente. O SDK mantém uma referência ao seu mecanismo de consulta periódica, mas o ciclo de vida do aplicativo, a execução em segundo plano, o cancelamento e o acesso a arquivos que permita retomar uploads ainda precisam de integração e testes nos dispositivos de destino. Essas funções auxiliares não constituem um aplicativo completo de upload em segundo plano.

Documentação

Consulte o GitHub para ver a documentação completa.