Tiercel Documentation

Add Tiercel to your Podfile. Ensure your platform is set to ios with version 12.0 or higher and use_frameworks! is enabled.

platform :ios, '12.0'
use_frameworks!

target 'YourTargetName' do
  pod 'Tiercel'
end

Then run:

pod install

To start downloading, create a SessionConfiguration, initialize a SessionManager with a unique identifier, and call .download(url). You can then attach callbacks for progress, success, or failure.

import Tiercel

var configuration = SessionConfiguration()
configuration.allowsCellularAccess = true
configuration.maxConcurrentTasksLimit = 3

let manager = SessionManager("downloads", configuration: configuration)

let task = manager.download("https://example.com/video.mp4")

task?.progress(onMainQueue: true) { task in
    print("progress:", task.progress.fractionCompleted)
}.success { task in
    print("saved to:", task.filePath)
}.failure { _ in
    print("download failed")
}

In Xcode, navigate to File > Add Package Dependencies... and use the following repository URL:

https://github.com/Danie1s/Tiercel.git

Tiercel persists task metadata and resume data to disk to support recovery after app restarts. To support native background session callbacks, you must pass the completion handler from AppDelegate to the corresponding SessionManager using its identifier.

let downloadManagers = [managerA, managerB]

func application(_ application: UIApplication,
                 handleEventsForBackgroundURLSession identifier: String,
                 completionHandler: @escaping () -> Void) {
    for manager in downloadManagers where manager.identifier == identifier {
        manager.completionHandler = completionHandler
        break
    }
}

Use SessionConfiguration to control network access permissions and concurrency limits for a SessionManager.

var configuration = SessionConfiguration()
configuration.maxConcurrentTasksLimit = 3
configuration.allowsCellularAccess = true
configuration.allowsConstrainedNetworkAccess = true
configuration.allowsExpensiveNetworkAccess = true

let manager = SessionManager("downloads", configuration: configuration)

Use SessionConfiguration to define how tasks behave regarding network constraints. Available properties include:

• maxConcurrentTasksLimit: Maximum number of concurrent tasks.
• allowsCellularAccess: Whether to allow cellular data.
• allowsConstrainedNetworkAccess: Whether to allow constrained networks.
• allowsExpensiveNetworkAccess: Whether to allow expensive networks.

var configuration = SessionConfiguration()
configuration.maxConcurrentTasksLimit = 3
configuration.allowsCellularAccess = true
configuration.allowsConstrainedNetworkAccess = true
configuration.allowsExpensiveNetworkAccess = true

let manager = SessionManager("downloads", configuration: configuration)

You can manage active downloads using either the source URL or the returned task instance via the SessionManager methods: start, suspend, cancel, and remove.

let url = "https://example.com/video.mp4"

manager.start(url)
manager.suspend(url)
manager.cancel(url)
manager.remove(url, completely: false)

if let task = task {
    manager.start(task)
    manager.suspend(task)
    manager.cancel(task)
    manager.remove(task, completely: false)
}

Initialize a SessionConfiguration, create a SessionManager with a unique identifier, and use the .download(_:) method to start a task. You can chain .progress and .success/.failure handlers.

import Tiercel

var configuration = SessionConfiguration()
configuration.allowsCellularAccess = true
configuration.maxConcurrentTasksLimit = 3

let manager = SessionManager("downloads", configuration: configuration)

let task = manager.download("https://example.com/video.mp4")

task?.progress(onMainQueue: true) { task in
    print("progress:", task.progress.fractionCompleted)
}.success { task in
    print("saved to:", task.filePath)
}.failure { _ in
    print("download failed")
}

Use multiDownload(_:) on a SessionManager to create multiple download tasks from an array of URLs simultaneously.

let urls = [
    "https://example.com/episode-1.mp4",
    "https://example.com/episode-2.mp4"
]

let tasks = manager.multiDownload(urls)
print(tasks.count)

You can control downloads using either the URL or the task instance directly through the SessionManager methods: start, suspend, cancel, and remove.

let url = "https://example.com/video.mp4"

// Using URL
manager.start(url)
manager.suspend(url)
manager.cancel(url)
manager.remove(url, completely: false)

// Using Task instance
if let task = task {
    manager.start(task)
    manager.suspend(task)
    manager.cancel(task)
    manager.remove(task, completely: false)
}