# TransloaditKit
[transloadit/transloaditkit](https://github.com/transloadit/transloaditkit)
TransloaditKit provides file uploading and processing for iOS and macOS apps. This guide uses the Swift API in TransloaditKit `3.5.0`, with TUSKit `3.6.0` in the verified setup below. Earlier Objective-C releases have different APIs; see the [original announcement](/blog/2017/11/ios-sdk.md) for that release history.
## Install
### CocoaPods
```ruby
pod 'Transloadit', '3.5.0'
pod 'TUSKit', '3.6.0'
```
The pod’s dependency range is `~> 3.6.0` (at least `3.6.0`, below `3.7.0`). Pin TUSKit explicitly to use the version verified here, and keep `Podfile.lock` with your project.
### Swift Package Manager
Add `https://github.com/transloadit/TransloaditKit` in Xcode’s package settings with an exact version of `3.5.0`, and select the `TransloaditKit` library product. This version pins TUSKit to `3.6.0`. Keep the resolved dependency versions with your project.
CocoaPods exposes the `Transloadit` module; Swift Package Manager exposes `TransloaditKit`. The conditional import below supports either installation.
## Usage
Never put the Auth Secret in an app binary, `Info.plist`, or configuration downloaded by the app, including internal apps. Keep it on your backend and require [Signature Authentication](/docs/api/authentication.md) for the Workspace or Template used by the app.
The `apiKey:sessionConfiguration:signatureGenerator:` initializer accepts a signature without requiring the Auth Secret. The SDK supplies the exact serialized `params` string to sign. Your backend must authenticate the user’s session and authorize the requested upload, allowing only the expected Auth Key, processing instructions, destinations, and expiry. Reject extra Steps, arbitrary Templates, fields, and unknown options. A logged-in caller must not be able to use the backend to sign arbitrary JSON. Apply quotas and upload restrictions on the server; for a server-owned Template, disable `allow_steps_override` and allow only that Template.
There are two constraints in this pinned release:
* Assembly creation fixes `auth.expires` at 24 hours in the future. The signing callback cannot replace those parameters. If your server policy requires a shorter expiry, reject the request and use backend Assembly creation or a different [Assembly API](/docs/api/assemblies-post.md) integration with server-controlled parameters. Do not extend your policy to accommodate the SDK.
* The `SignatureCompletion` parameter is nonescaping: call it before the signature generator returns. A normal asynchronous HTTP completion cannot capture it. The helper below accepts a synchronous backend transport and must be used off the main thread. That transport must have a finite timeout and throw on failure; the SDK provides no signing timeout or fallback.
Your app supplies `requestSignature`, its authenticated HTTPS integration with your own backend. Send the original params string unchanged and the current user session token in the request’s `Authorization` header, using a fixed trusted endpoint, rejecting redirects and unsuccessful HTTP responses. The token belongs to your app’s login system, not to Transloadit. The backend validates the request and signs the approved original UTF-8 bytes with HMAC-SHA384. It returns the same params string and a signature, never the Auth Secret. Do not reserialize or change expiry after approval. Refresh the session before making a new client when it expires.
The complete helper below checks that the backend approved these exact params and supplied a well-formed signature. Client checks do not replace backend authorization. `ApprovedSignature` is this example’s response type, not an SDK type.
```swift
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
})
}
)
}
```
### Create an Assembly
This complete helper creates a resize Step, queues the supplied local files for upload, and registers a processing-status callback. Include it alongside the client helper above. The backend policy for this example must allow exactly this 200 × 100 `fit` resize with `result: true`. The upload file count travels outside signed params in this SDK, so it is not an authorization limit. If your required file restrictions cannot be enforced by the selected workflow, create the Assembly through your backend instead of issuing a broader signature.
```swift
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) -> Void,
status: @escaping (Result) -> Void
) -> TransloaditPoller {
let poller = client.createAssembly(
steps: [makeResizeStep()], andUpload: files, completion: created
)
poller.pollAssemblyStatus(completion: status)
return poller
}
```
Pass readable local file URLs from your app’s file selection to `uploadImages`, and retain the `Transloadit` client for the operation. Call it on a background queue because signing is synchronous; dispatch UI updates from callbacks to the main queue. Handle failure in both callbacks. A successful `created` callback means the Assembly exists and uploads were queued, not that uploading or processing finished. In the status callback, inspect `processingStatus`: `completed`, `aborted`, and `canceled` are distinct terminal outcomes.
For file progress and upload errors, implement and retain a `TransloaditFileDelegate` and assign it to the client’s weak `fileDelegate` property. The SDK retains its poller, but app lifecycle, background execution, cancellation, and resumable file access still need integration and testing on your target devices. These helpers are not a complete background-upload application.
## Documentation
See [GitHub](https://github.com/transloadit/TransloaditKit#readme) for the full documentation.