TransloaditKit

TransloaditKit permite subir y procesar archivos en aplicaciones para iOS y macOS. Esta guía usa la API Swift de TransloaditKit 3.5.0, con TUSKit 3.6.0 en la configuración verificada que aparece a continuación. Las versiones anteriores de Objective-C tienen API diferentes; consulta el anuncio original para conocer el historial de esas versiones.

Instalación

CocoaPods

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

El rango de versiones de la dependencia del pod es ~> 3.6.0 (como mínimo 3.6.0, inferior a 3.7.0). Fija TUSKit explícitamente para usar la versión verificada aquí y conserva Podfile.lock junto con tu proyecto.

Swift Package Manager

Añade https://github.com/transloadit/TransloaditKit en la configuración de paquetes de Xcode con la versión exacta 3.5.0 y selecciona el producto de biblioteca TransloaditKit. Esta versión fija TUSKit a 3.6.0. Conserva las versiones resueltas de las dependencias junto con tu proyecto.

CocoaPods expone el módulo Transloadit; Swift Package Manager expone TransloaditKit. La importación condicional que aparece a continuación admite cualquiera de las dos instalaciones.

Uso

Nunca incluyas el Auth Secret en el binario de una app, Info.plist ni en la configuración que descarga la app, tampoco en apps internas. Mantenlo en tu backend y exige Signature Authentication para el Workspace o Template que use la app.

El inicializador apiKey:sessionConfiguration:signatureGenerator: acepta una firma sin requerir el Auth Secret. El SDK proporciona la cadena serializada exacta de params que se debe firmar. Tu backend debe autenticar la sesión del usuario y autorizar la subida solicitada, permitiendo solo los valores previstos para la Auth Key, las instrucciones de procesamiento, los destinos y el vencimiento. Rechaza Steps adicionales, Templates arbitrarios, campos y opciones desconocidas. Quien haga la solicitud con una sesión iniciada no debe poder usar el backend para firmar JSON arbitrario. Aplica cuotas y restricciones de subida en el servidor; para un Template del servidor, desactiva allow_steps_override y permite únicamente ese Template.

Esta versión fijada tiene dos limitaciones:

La creación de Assemblies fija auth.expires a 24 horas en el futuro. El callback de firma no puede sustituir esos parámetros. Si la política de tu servidor exige un plazo de vencimiento más corto, rechaza la solicitud y crea la Assembly desde el backend o usa otra integración de la API de Assemblies con parámetros controlados por el servidor. No amplíes los límites de tu política para adaptarla al SDK.
El parámetro SignatureCompletion es nonescaping: invócalo antes de que el generador de firmas retorne. Un callback normal de finalización HTTP asíncrona no puede capturarlo. La función auxiliar que aparece a continuación acepta un transporte síncrono al backend y debe usarse fuera del hilo principal. Ese transporte debe tener un tiempo de espera finito y lanzar una excepción si falla; el SDK no ofrece un tiempo de espera para la firma ni un mecanismo alternativo.

Tu app proporciona requestSignature, su integración HTTPS autenticada con tu propio backend. Envía la cadena original de parámetros sin cambios y el token de la sesión actual del usuario en el encabezado Authorization de la solicitud. Usa un endpoint fijo de confianza y rechaza las redirecciones y las respuestas HTTP que no indiquen éxito. El token pertenece al sistema de inicio de sesión de tu app, no a Transloadit. El backend valida la solicitud y firma los bytes UTF-8 originales aprobados con HMAC-SHA384. Devuelve la misma cadena de parámetros y una firma, nunca el Auth Secret. No vuelvas a serializar los parámetros ni cambies el vencimiento después de la aprobación. Cuando la sesión venza, renuévala antes de crear un cliente nuevo.

La función auxiliar completa que aparece a continuación comprueba que el backend haya aprobado estos parámetros exactos y proporcionado una firma con el formato correcto. Las comprobaciones del cliente no sustituyen la autorización del backend. ApprovedSignature es el tipo de respuesta de este ejemplo, no un tipo del 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
            })
        }
    )
}

Crea una Assembly

Esta función auxiliar completa crea un Step de cambio de tamaño, pone en cola los archivos locales proporcionados para subirlos y registra un callback de estado del procesamiento. Inclúyela junto con la función auxiliar del cliente anterior. La política del backend para este ejemplo debe permitir exactamente este cambio de tamaño a 200 × 100 mediante fit con result: true. En este SDK, la cantidad de archivos que se subirán se transmite fuera de los parámetros firmados, por lo que no constituye un límite de autorización. Si el flujo de trabajo seleccionado no permite aplicar las restricciones de archivos que necesitas, crea la Assembly a través de tu backend en lugar de emitir una firma de mayor alcance.

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
}

Pasa las URL de archivos locales que se puedan leer, obtenidas de la selección de archivos de tu app, a uploadImages y conserva el cliente Transloadit durante la operación. Invoca la función en una cola en segundo plano porque la firma es síncrona; envía las actualizaciones de la interfaz de usuario desde los callbacks a la cola principal. Gestiona los fallos en ambos callbacks. Un callback created exitoso significa que la Assembly existe y las subidas se pusieron en cola, no que la subida o el procesamiento hayan terminado. En el callback de estado, inspecciona processingStatus: completed, aborted y canceled son resultados finales distintos.

Para gestionar el progreso de los archivos y los errores de subida, implementa y conserva un TransloaditFileDelegate y asígnalo a la propiedad de referencia débil fileDelegate del cliente. El SDK conserva su mecanismo de consulta periódica, pero el ciclo de vida de la app, la ejecución en segundo plano, la cancelación y el acceso a los archivos para reanudar las subidas aún requieren integración y pruebas en los dispositivos de destino. Estas funciones auxiliares no constituyen una aplicación completa de subida en segundo plano.

Documentación

Consulta la documentación completa en GitHub.