TransloaditKit

TransloaditKit ermöglicht das Hochladen und Verarbeiten von Dateien in iOS- und macOS-Apps. Diese Anleitung verwendet die Swift-API in TransloaditKit 3.5.0 mit TUSKit 3.6.0 in der unten gezeigten, verifizierten Konfiguration. Frühere Objective-C-Versionen haben andere APIs; die Versionsgeschichte finden Sie in der ursprünglichen Ankündigung.

Installation

CocoaPods

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

Der Versionsbereich der Pod-Abhängigkeit ist ~> 3.6.0 (mindestens 3.6.0, unter 3.7.0). Legen Sie TUSKit explizit auf die hier verifizierte Version fest und bewahren Sie Podfile.lock zusammen mit Ihrem Projekt auf.

Swift Package Manager

Fügen Sie https://github.com/transloadit/TransloaditKit in den Paketeinstellungen von Xcode mit der exakten Version 3.5.0 hinzu und wählen Sie das Bibliotheksprodukt TransloaditKit aus. Diese Version legt TUSKit auf 3.6.0 fest. Bewahren Sie die aufgelösten Abhängigkeitsversionen zusammen mit Ihrem Projekt auf.

CocoaPods stellt das Modul Transloadit bereit, Swift Package Manager hingegen TransloaditKit. Der folgende bedingte Import unterstützt beide Installationsarten.

Verwendung

Hinterlegen Sie das Auth Secret niemals in einer App-Binärdatei, in Info.plist oder in einer Konfiguration, die die App herunterlädt. Das gilt auch für interne Apps. Bewahren Sie es in Ihrem Backend auf und verlangen Sie Signature Authentication für den Workspace oder das Template, den beziehungsweise das die App verwendet.

Der Initialisierer apiKey:sessionConfiguration:signatureGenerator: akzeptiert eine Signatur, ohne das Auth Secret zu benötigen. Das SDK liefert die serialisierte Zeichenfolge params, deren unveränderte Bytes signiert werden sollen. Ihr Backend muss die Sitzung der nutzenden Person authentifizieren und den angeforderten Upload autorisieren. Dabei darf es nur den erwarteten Auth Key, die vorgesehenen Verarbeitungsanweisungen, Ziele und Ablaufzeit zulassen. Weisen Sie zusätzliche Steps, beliebige Templates, Felder und unbekannte Optionen zurück. Auch angemeldete Aufrufer dürfen das Backend nicht zum Signieren beliebiger JSON-Daten nutzen können. Setzen Sie Kontingente und Upload-Beschränkungen auf dem Server durch; deaktivieren Sie bei einem servereigenen Template allow_steps_override und lassen Sie nur dieses Template zu.

Für diese festgelegte Version gelten zwei Einschränkungen:

Beim Erstellen einer Assembly wird auth.expires auf 24 Stunden in der Zukunft festgelegt. Der Signatur-Callback kann diese Parameter nicht ersetzen. Wenn Ihre Serverrichtlinie eine kürzere Gültigkeit verlangt, weisen Sie die Anfrage zurück und erstellen Sie die Assembly im Backend oder nutzen Sie eine andere Integration der Assembly-API mit serverseitig gesteuerten Parametern. Lockern Sie Ihre Richtlinie nicht, um dem SDK zu entsprechen.
Der Parameter SignatureCompletion ist nonescaping: Rufen Sie ihn auf, bevor der Signaturgenerator zurückkehrt. Ein normaler asynchroner HTTP-Completion-Handler kann ihn nicht erfassen. Die folgende Hilfsfunktion akzeptiert einen synchronen Backend-Transport und muss außerhalb des Hauptthreads verwendet werden. Dieser Transport muss ein endliches Zeitlimit haben und bei einem Fehler eine Ausnahme auslösen; das SDK bietet weder ein Zeitlimit für das Signieren noch eine Ausweichlösung.

Ihre App stellt requestSignature bereit, ihre authentifizierte HTTPS-Integration mit Ihrem eigenen Backend. Senden Sie die ursprüngliche Parameterzeichenfolge unverändert und das aktuelle Sitzungstoken der nutzenden Person im Header Authorization der Anfrage. Verwenden Sie dabei einen festen, vertrauenswürdigen Endpunkt und weisen Sie Weiterleitungen sowie nicht erfolgreiche HTTP-Antworten zurück. Das Token gehört zum Anmeldesystem Ihrer App, nicht zu Transloadit. Das Backend validiert die Anfrage und signiert die genehmigten ursprünglichen UTF-8-Bytes mit HMAC-SHA384. Es gibt dieselbe Parameterzeichenfolge und eine Signatur zurück, niemals das Auth Secret. Serialisieren Sie die Parameter nach der Genehmigung nicht erneut und ändern Sie die Ablaufzeit nicht. Wenn die Sitzung abläuft, erneuern Sie sie, bevor Sie einen neuen Client erstellen.

Die folgende vollständige Hilfsfunktion prüft, ob das Backend genau diese Parameter genehmigt und eine korrekt formatierte Signatur geliefert hat. Clientseitige Prüfungen ersetzen keine Autorisierung im Backend. ApprovedSignature ist der Antworttyp dieses Beispiels, kein SDK-Typ.

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
            })
        }
    )
}

Eine Assembly erstellen

Diese vollständige Hilfsfunktion erstellt einen Step zur Größenänderung, reiht die übergebenen lokalen Dateien zum Upload in die Warteschlange ein und registriert einen Callback für den Verarbeitungsstatus. Binden Sie sie zusammen mit der obigen Client-Hilfsfunktion ein. Die Backend-Richtlinie für dieses Beispiel muss genau diese Größenänderung auf 200 × 100 mit fit und result: true erlauben. Die Anzahl der hochzuladenden Dateien wird in diesem SDK außerhalb der signierten Parameter übertragen und stellt daher keine Autorisierungsgrenze dar. Wenn sich Ihre erforderlichen Dateibeschränkungen mit dem gewählten Workflow nicht durchsetzen lassen, erstellen Sie die Assembly über Ihr Backend, statt eine Signatur mit weiterreichenden Berechtigungen auszustellen.

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
}

Übergeben Sie lesbare lokale Datei-URLs aus der Dateiauswahl Ihrer App an uploadImages und halten Sie den Client Transloadit für den Vorgang im Speicher. Führen Sie den Aufruf in einer Hintergrund-Queue aus, da das Signieren synchron erfolgt; leiten Sie UI-Aktualisierungen aus Callbacks an die Haupt-Queue weiter. Behandeln Sie Fehler in beiden Callbacks. Ein erfolgreicher Callback created bedeutet, dass die Assembly existiert und die Uploads in die Warteschlange eingereiht wurden, nicht, dass das Hochladen oder die Verarbeitung abgeschlossen ist. Prüfen Sie im Status-Callback processingStatus: completed, aborted und canceled sind unterschiedliche Endzustände.

Implementieren Sie für den Dateifortschritt und Upload-Fehler ein Objekt vom Typ TransloaditFileDelegate, halten Sie es im Speicher und weisen Sie es der schwachen Eigenschaft fileDelegate des Clients zu. Das SDK hält seinen Poller im Speicher, aber App-Lebenszyklus, Hintergrundausführung, Abbruch und wiederaufnehmbarer Dateizugriff müssen weiterhin integriert und auf Ihren Zielgeräten getestet werden. Diese Hilfsfunktionen bilden keine vollständige Anwendung für Hintergrund-Uploads.

Dokumentation

Die vollständige Dokumentation finden Sie auf GitHub.