TransloaditKit

TransloaditKit permet l’envoi et le traitement de fichiers dans les apps iOS et macOS. Ce guide utilise l’API Swift de TransloaditKit 3.5.0, avec TUSKit 3.6.0 dans la configuration vérifiée ci-dessous. Les versions Objective-C antérieures ont des API différentes ; consultez l’annonce d’origine (English) pour l’historique de ces versions.

Installation

CocoaPods

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

La plage de dépendance du pod est ~> 3.6.0 (au moins 3.6.0, inférieure à 3.7.0). Fixez explicitement la version de TUSKit pour utiliser celle vérifiée ici, et conservez Podfile.lock avec votre projet.

Swift Package Manager

Ajoutez https://github.com/transloadit/TransloaditKit dans les réglages de paquets d’Xcode avec la version exacte 3.5.0, puis sélectionnez le produit de bibliothèque TransloaditKit. Cette version fixe TUSKit à 3.6.0. Conservez les versions de dépendances résolues avec votre projet.

CocoaPods expose le module Transloadit ; Swift Package Manager expose TransloaditKit. L’import conditionnel ci-dessous prend en charge les deux modes d’installation.

Utilisation

Ne placez jamais l’Auth Secret dans un binaire d’app, Info.plist ou une configuration téléchargée par l’app, y compris pour les apps internes. Conservez-le sur votre backend et exigez la Signature Authentication pour le Workspace ou le Template utilisé par l’app.

L’initialiseur apiKey:sessionConfiguration:signatureGenerator: accepte une signature sans exiger l’Auth Secret. Le SDK fournit la chaîne params sérialisée exacte à signer. Votre backend doit authentifier la session de l’utilisateur et autoriser l’envoi demandé, en n’autorisant que l’Auth Key, les instructions de traitement, les destinations et l’expiration prévues. Rejetez les Steps supplémentaires, les Templates arbitraires, les champs et les options inconnues. Un appelant connecté ne doit pas pouvoir utiliser le backend pour signer du JSON arbitraire. Appliquez les quotas et les restrictions d’envoi sur le serveur ; pour un Template détenu par le serveur, désactivez allow_steps_override et n’autorisez que ce Template.

Cette version fixée comporte deux contraintes :

La création d’une Assembly fixe auth.expires à 24 heures dans le futur. Le callback de signature ne peut pas remplacer ces paramètres. Si la politique de votre serveur exige une expiration plus courte, rejetez la requête et utilisez la création d’Assembly côté backend ou une autre intégration de l’API Assembly avec des paramètres contrôlés par le serveur. N’assouplissez pas votre politique pour vous adapter au SDK.
Le paramètre SignatureCompletion est non échappant (nonescaping) : appelez-le avant que le générateur de signature ne retourne. Une complétion HTTP asynchrone normale ne peut pas le capturer. La fonction utilitaire ci-dessous accepte un transport backend synchrone et doit être utilisée hors du thread principal. Ce transport doit avoir un délai d’expiration fini et lever une erreur en cas d’échec ; le SDK ne fournit ni délai d’expiration pour la signature, ni solution de repli.

Votre app fournit requestSignature, son intégration HTTPS authentifiée avec votre propre backend. Envoyez la chaîne de params d’origine sans modification et le jeton de session de l’utilisateur courant dans l’en-tête Authorization de la requête, en utilisant un endpoint de confiance fixe et en rejetant les redirections et les réponses HTTP en échec. Le jeton appartient au système de connexion de votre app, pas à Transloadit. Le backend valide la requête et signe les octets UTF-8 d’origine approuvés avec HMAC-SHA384. Il renvoie la même chaîne de params et une signature, jamais l’Auth Secret. Ne resérialisez pas les params et ne modifiez pas l’expiration après approbation. Lorsque la session expire, actualisez-la avant de créer un nouveau client.

La fonction utilitaire complète ci-dessous vérifie que le backend a approuvé exactement ces params et fourni une signature bien formée. Les vérifications côté client ne remplacent pas l’autorisation côté backend. ApprovedSignature est le type de réponse de cet exemple, et non un type du 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
            })
        }
    )
}

Créer une Assembly

Cette fonction utilitaire complète crée un Step de redimensionnement, met en file d’attente les fichiers locaux fournis pour l’envoi et enregistre un callback d’état de traitement. Incluez-la avec la fonction utilitaire client ci-dessus. La politique backend de cet exemple doit autoriser exactement ce redimensionnement 200 × 100 fit avec result: true. Dans ce SDK, le nombre de fichiers envoyés transite en dehors des params signés : ce n’est donc pas une limite d’autorisation. Si les restrictions de fichiers dont vous avez besoin ne peuvent pas être appliquées par le flux de travail choisi, créez l’Assembly via votre backend au lieu d’émettre une signature plus large.

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
}

Passez à uploadImages des URL de fichiers locaux lisibles issues de la sélection de fichiers de votre app, et conservez le client Transloadit pendant toute l’opération. Appelez cette fonction sur une file d’arrière-plan, car la signature est synchrone ; renvoyez les mises à jour d’interface déclenchées par les callbacks vers la file principale. Gérez les échecs dans les deux callbacks. Un callback created réussi signifie que l’Assembly existe et que les envois ont été mis en file d’attente, et non que l’envoi ou le traitement est terminé. Dans le callback d’état, examinez processingStatus : completed, aborted et canceled sont des issues finales distinctes.

Pour la progression des fichiers et les erreurs d’envoi, implémentez et conservez un TransloaditFileDelegate, puis assignez-le à la propriété faible fileDelegate du client. Le SDK conserve son mécanisme d’interrogation, mais le cycle de vie de l’app, l’exécution en arrière-plan, l’annulation et l’accès aux fichiers pour la reprise des envois nécessitent encore une intégration et des tests sur vos appareils cibles. Ces fonctions utilitaires ne constituent pas une application complète d’envoi en arrière-plan.

Documentation

Consultez GitHub pour la documentation complète.