URLSession Tutorial: Getting Started
In this URLSession tutorial, you’ll learn how to create HTTP requests as well as implement background downloads that can be both paused and resumed. By Felipe Laso-Marsetti.
Sign up/Sign in
With a free Kodeco account you can download source code, track your progress, bookmark, personalise your learner profile and more!
Create accountAlready a member of Kodeco? Sign in
Sign up/Sign in
With a free Kodeco account you can download source code, track your progress, bookmark, personalise your learner profile and more!
Create accountAlready a member of Kodeco? Sign in
Contents
URLSession Tutorial: Getting Started
30 mins
- Getting Started
- URLSession Overview
- Understanding Session Task Types
- DataTask and DownloadTask
- Downloading Classes
- URLSession Delegates
- Downloading a Track
- Saving and Playing the Track
- Pausing, Resuming, and Canceling Downloads
- Canceling Downloads
- Pausing Downloads
- Resuming Downloads
- Showing and Hiding the Pause/Resume and Cancel Buttons
- Showing Download Progress
- Displaying the Download’s Progress
- Enabling Background Transfers
- Relaunching Your App
- Testing Your App’s Functionality
- Where to Go From Here?
Whether an app retrieves application data from a server, updates your social media status or downloads remote files to disk, network requests are what make the magic happen. To help you with the many requirements for network requests, Apple provides URLSession
, a complete networking API for uploading and downloading content.
In this tutorial, you’ll learn how to build Half Tunes, an app that queries the iTunes Search API, then downloads 30-second previews of songs. The finished app will support background transfers and let the user pause, resume or cancel in-progress downloads.
Getting Started
Use the Download Materials button at the top or bottom of this tutorial to download the starter project.
The starter project contains a user interface to search for songs and display search results, networking classes with some stubbed functionality and helper methods to store and play tracks. This lets you focus on implementing the networking aspects of the app.
Build and run the project. You’ll see a view with a search bar at the top and an empty table view below:
Type a query in the search bar and tap Search. The view remains empty. Don’t worry though, you’ll change this with your new URLSession
calls.
URLSession Overview
Before you begin, it’s important to understand URLSession
and its constituent classes, so take a look at the quick overview below.
URLSession
is both a class and a suite of classes for handling HTTP- and HTTPS-based requests:
URLSession
is the key object responsible for sending and receiving requests. You create it via URLSessionConfiguration
, which comes in three flavors:
- default: Creates a default configuration object that uses the disk-persisted global cache, credential and cookie storage objects.
- ephemeral: Similar to the default configuration, except that you store all of the session-related data in memory. Think of this as a “private” session.
- background: Lets the session perform upload or download tasks in the background. Transfers continue even when the app itself is suspended or terminated by the system.
URLSessionConfiguration
also lets you configure session properties such as timeout values, caching policies and HTTP headers. Refer to Apple’s documentation for a full list of configuration options.
URLSessionTask
is an abstract class that denotes a task object. A session creates one or more tasks to do the actual work of fetching data and downloading or uploading files.
Understanding Session Task Types
There are three types of concrete session tasks:
- URLSessionDataTask: Use this task for GET requests to retrieve data from servers to memory.
- URLSessionUploadTask: Use this task to upload a file from disk to a web service via a POST or PUT method.
- URLSessionDownloadTask: Use this task to download a file from a remote service to a temporary file location.
You can also suspend, resume and cancel tasks. URLSessionDownloadTask
has the extra ability to pause for future resumption.
Generally, URLSession
returns data in two ways:
- Via a completion handler when a task finishes, either successfully or with an error; or,
- By calling methods on a delegate that you set when you create the session.
Now that you have an overview of what URLSession
can do, you’re ready to put the theory into practice!
DataTask and DownloadTask
You’ll start by creating a data task to query the iTunes Search API for the user’s search term.
In SearchViewController.swift, searchBarSearchButtonClicked
enables the network activity indicator on the status bar to show the user that a network process is running. Then it calls getSearchResults(searchTerm:completion:)
, which is stubbed out in QueryService.swift. You’re about to build it out to make the network request.
In QueryService.swift, replace // TODO 1
with the following:
let defaultSession = URLSession(configuration: .default)
And // TODO 2
with:
var dataTask: URLSessionDataTask?
Here’s what you’ve done:
- Created a
URLSession
and initialized it with a default session configuration. - Declared
URLSessionDataTask
, which you’ll use to make a GET request to the iTunes Search web service when the user performs a search. The data task will be re-initialized each time the user enters a new search string.
Next, replace the content in getSearchResults(searchTerm:completion:)
with the following:
// 1
dataTask?.cancel()
// 2
if var urlComponents = URLComponents(string: "https://itunes.apple.com/search") {
urlComponents.query = "media=music&entity=song&term=\(searchTerm)"
// 3
guard let url = urlComponents.url else {
return
}
// 4
dataTask =
defaultSession.dataTask(with: url) { [weak self] data, response, error in
defer {
self?.dataTask = nil
}
// 5
if let error = error {
self?.errorMessage += "DataTask error: " +
error.localizedDescription + "\n"
} else if
let data = data,
let response = response as? HTTPURLResponse,
response.statusCode == 200 {
self?.updateSearchResults(data)
// 6
DispatchQueue.main.async {
completion(self?.tracks, self?.errorMessage ?? "")
}
}
}
// 7
dataTask?.resume()
}
Taking each numbered comment in turn:
- For a new user query, you cancel any data task that already exists, because you want to reuse the data task object for this new query.
- To include the user’s search string in the query URL, you create
URLComponents
from the iTunes Search base URL, then set its query string. This ensures that your search string uses escaped characters. If you get back an error message, omit themedia
andentity
components: See this forum post. - The
url
property ofurlComponents
is optional, so you unwrap it tourl
and return early if it’snil
. - From the session you created, you initialize a
URLSessionDataTask
with the queryurl
and a completion handler to call when the data task completes. - If the request is successful, you call the helper method
updateSearchResults
, which parses the responsedata
into thetracks
array. - You switch to the main queue to pass
tracks
to the completion handler. - All tasks start in a suspended state by default. Calling
resume()
starts the data task.
In SearchViewController
, take a look at the completion closure in the call to getSearchResults(searchTerm:completion:)
. After hiding the activity indicator, it stores results
in searchResults
then updates the table view.
URLRequest
with url
, set the request’s HTTPMethod
property then create a data task with the URLRequest
instead of with the URL
.Build and run your app. Search for any song and you’ll see the table view populate with the relevant track results like so:
With some URLSession
code, Half Tunes is now a bit functional!
Being able to view song results is nice, but wouldn’t it be better if you could tap a song to download it? That’s your next order of business. You’ll use a download task, which makes it easy to save the song snippet in a local file.
Downloading Classes
The first thing you’ll need to do to handle multiple downloads is to create a custom object to hold the state of an active download.
Create a new Swift file named Download.swift in the Model group.
Open Download.swift, and add the following implementation below the Foundation import
:
class Download {
var isDownloading = false
var progress: Float = 0
var resumeData: Data?
var task: URLSessionDownloadTask?
var track: Track
init(track: Track) {
self.track = track
}
}
Here’s a rundown of the properties of Download
:
- isDownloading: Whether the download is ongoing or paused.
- progress: The fractional progress of the download, expressed as a float between 0.0 and 1.0.
-
resumeData: Stores the
Data
produced when the user pauses a download task. If the host server supports it, your app can use this to resume a paused download. -
task: The
URLSessionDownloadTask
that downloads the track. -
track: The track to download. The track’s
url
property also acts as a unique identifier forDownload
.
Next, in DownloadService.swift, replace // TODO 4
with the following property:
var activeDownloads: [URL: Download] = [:]
This dictionary will maintain a mapping between a URL and its active Download
, if any.
URLSession Delegates
You could create your download task with a completion handler, as you did when you created the data task. However, later in this tutorial you’ll check and update the download progress, which requires you to implement a custom delegate. So you might as well do that now.
There are several session delegate protocols, listed in Apple’s URLSession documentation. URLSessionDownloadDelegate
handles task-level events specific to download tasks.
You’re going to need to set SearchViewController
as the session delegate soon, so now you’ll create an extension to conform to the session delegate protocol.
Open SearchViewController.swift and replace // TODO 5
with the following URLSessionDownloadDelegate
extension below:
extension SearchViewController: URLSessionDownloadDelegate {
func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask,
didFinishDownloadingTo location: URL) {
print("Finished downloading to \(location).")
}
}
The only non-optional URLSessionDownloadDelegate
method is urlSession(_:downloadTask:didFinishDownloadingTo:)
, which your app calls when a download finishes. For now, you’ll print a message whenever a download completes.
Downloading a Track
With all the preparatory work out of the way, you’re now ready to put file downloads in place. Your first step is to create a dedicated session to handle your download tasks.
In SearchViewController.swift, replace // TODO 6
with the following code:
lazy var downloadsSession: URLSession = {
let configuration = URLSessionConfiguration.default
return URLSession(configuration: configuration,
delegate: self,
delegateQueue: nil)
}()
Here, you initialize a separate session with a default configuration and specify a delegate which lets you receive URLSession
events via delegate calls. This will be useful for monitoring the progress of the task.
Setting the delegate queue to nil
causes the session to create a serial operation queue to perform all calls to delegate methods and completion handlers.
Note the lazy creation of downloadsSession
; this lets you delay the creation of the session until after you initialize the view controller. Doing that allows you to pass self
as the delegate parameter to the session initializer.
Now replace // TODO 7
at the end of viewDidLoad()
with the following line:
downloadService.downloadsSession = downloadsSession
This sets the downloadsSession
property of DownloadService
to the session you just defined.
With your session and delegate configured, you’re finally ready to create a download task when the user requests a track download.
In DownloadService.swift, replace the content of startDownload(_:)
with the following implementation:
// 1
let download = Download(track: track)
// 2
download.task = downloadsSession.downloadTask(with: track.previewURL)
// 3
download.task?.resume()
// 4
download.isDownloading = true
// 5
activeDownloads[download.track.previewURL] = download
When the user taps a table view cell’s Download button, SearchViewController
, acting as TrackCellDelegate
, identifies the Track
for this cell, then calls startDownload(_:)
with that Track
.
Here’s what’s going on in startDownload(_:)
:
- You first initialize a
Download
with the track. - Using your new session object, you create a
URLSessionDownloadTask
with the track’s preview URL and set it to thetask
property of theDownload
. - You start the download task by calling
resume()
on it. - You indicate that the download is in progress.
- Finally, you map the download URL to its
Download
inactiveDownloads
.
Build and run your app, search for any track and tap the Download button on a cell. After a while, you’ll see a message in the debug console signifying that the download is complete.
Finished downloading to file:///Users/mymac/Library/Developer/CoreSimulator/Devices/74A1CE9B-7C49-46CA-9390-3B8198594088/data/Containers/Data/Application/FF0D263D-4F1D-4305-B98B-85B6F0ECFE16/tmp/CFNetworkDownload_BsbzIk.tmp.
The Download button is still showing, but you’ll fix that soon. First, you want to play some tunes!
Saving and Playing the Track
When a download task completes, urlSession(_:downloadTask:didFinishDownloadingTo:)
provides a URL to the temporary file location, as you saw in the print message. Your job is to move it to a permanent location in your app’s sandbox container directory before you return from the method.
In SearchViewController.swift, replace the print statement in urlSession(_:downloadTask:didFinishDownloadingTo:)
with the following code:
// 1
guard let sourceURL = downloadTask.originalRequest?.url else {
return
}
let download = downloadService.activeDownloads[sourceURL]
downloadService.activeDownloads[sourceURL] = nil
// 2
let destinationURL = localFilePath(for: sourceURL)
print(destinationURL)
// 3
let fileManager = FileManager.default
try? fileManager.removeItem(at: destinationURL)
do {
try fileManager.copyItem(at: location, to: destinationURL)
download?.track.downloaded = true
} catch let error {
print("Could not copy file to disk: \(error.localizedDescription)")
}
// 4
if let index = download?.track.index {
DispatchQueue.main.async { [weak self] in
self?.tableView.reloadRows(at: [IndexPath(row: index, section: 0)],
with: .none)
}
}
Here’s what you’re doing at each step:
- You extract the original request URL from the task, look up the corresponding
Download
in your active downloads and remove it from that dictionary. - You then pass the URL to
localFilePath(for:)
, which generates a permanent local file path to save to by appending thelastPathComponent
of the URL (the file name and extension of the file) to the path of the app’s Documents directory. - Using
fileManager
, you move the downloaded file from its temporary file location to the desired destination file path, first clearing out any item at that location before you start the copy task. You also set the download track’sdownloaded
property totrue
. - Finally, you use the download track’s
index
property to reload the corresponding cell.
Build and run your project, run a query, then pick any track and download it. When the download has finished, you’ll see the file path location printed to your console:
file:///Users/mymac/Library/Developer/CoreSimulator/Devices/74A1CE9B-7C49-46CA-9390-3B8198594088/data/Containers/Data/Application/087C38CC-0CEB-4895-ADB6-F44D13C2CA5A/Documents/mzaf_2494277700123015788.plus.aac.p.m4a
The Download button disappears now, because the delegate method set the track’s downloaded
property to true
. Tap the track and you’ll hear it play in the AVPlayerViewController
as shown below:
Pausing, Resuming, and Canceling Downloads
What if the user wants to pause a download or to cancel it altogether? In this section, you’ll implement the pause, resume and cancel features to give the user complete control over the download process.
You’ll start by allowing the user to cancel an active download.
Canceling Downloads
In DownloadService.swift, add the following code inside cancelDownload(_:)
:
guard let download = activeDownloads[track.previewURL] else {
return
}
download.task?.cancel()
activeDownloads[track.previewURL] = nil
To cancel a download, you’ll retrieve the download task from the corresponding Download
in the dictionary of active downloads and call cancel()
on it to cancel the task. You’ll then remove the download object from the dictionary of active downloads.
Pausing Downloads
Your next task is to let your users pause their downloads and come back to them later.
Pausing a download is similar to canceling it. Pausing cancels the download task, but also produces resume data, which contains enough information to resume the download at a later time if the host server supports that functionality.
Replace the contents of pauseDownload(_:)
with the following code:
guard
let download = activeDownloads[track.previewURL],
download.isDownloading
else {
return
}
download.task?.cancel(byProducingResumeData: { data in
download.resumeData = data
})
download.isDownloading = false
The key difference here is that you call cancel(byProducingResumeData:)
instead of cancel()
. You provide a closure parameter to this method, which lets you save the resume data to the appropriate Download
for future resumption.
You also set the isDownloading
property of the Download
to false
to indicate that the user has paused the download.
Now that the pause function is complete, the next order of business is to allow the user to resume a paused download.
Resuming Downloads
Replace the content of resumeDownload(_:)
with the following code:
guard let download = activeDownloads[track.previewURL] else {
return
}
if let resumeData = download.resumeData {
download.task = downloadsSession.downloadTask(withResumeData: resumeData)
} else {
download.task = downloadsSession
.downloadTask(with: download.track.previewURL)
}
download.task?.resume()
download.isDownloading = true
When the user resumes a download, you check the appropriate Download
for the presence of resume data. If found, you’ll create a new download task by invoking downloadTask(withResumeData:)
with the resume data. If the resume data is absent for any reason, you’ll create a new download task with the download URL.
In either case, you’ll start the task by calling resume
and set the isDownloading
flag of the Download
to true
to indicate the download has resumed.
Showing and Hiding the Pause/Resume and Cancel Buttons
There’s only one item left to do for these three functions to work: You need to show or hide the Pause/Resume and Cancel buttons, as appropriate.
To do this, TrackCell
‘s configure(track:downloaded:)
needs to know if the track has an active download and whether it’s currently downloading.
In TrackCell.swift, change configure(track:downloaded:)
to configure(track:downloaded:download:)
:
func configure(track: Track, downloaded: Bool, download: Download?) {
In SearchViewController.swift, fix the call in tableView(_:cellForRowAt:)
:
cell.configure(track: track,
downloaded: track.downloaded,
download: downloadService.activeDownloads[track.previewURL])
Here, you extract the track’s download object from activeDownloads
.
Back in TrackCell.swift, locate // TODO 14
in configure(track:downloaded:download:)
and add the following property:
var showDownloadControls = false
Then replace // TODO 15
with the following:
if let download = download {
showDownloadControls = true
let title = download.isDownloading ? "Pause" : "Resume"
pauseButton.setTitle(title, for: .normal)
}
As the comment notes, a non-nil download object means a download is in progress, so the cell should show the download controls: Pause/Resume and Cancel. Since the pause and resume functions share the same button, you’ll toggle the button between the two states, as appropriate.
Below this if-closure, add the following code:
pauseButton.isHidden = !showDownloadControls
cancelButton.isHidden = !showDownloadControls
Here, you show the buttons for a cell only if a download is active.
Finally, replace the last line of this method:
downloadButton.isHidden = downloaded
with the following code:
downloadButton.isHidden = downloaded || showDownloadControls
Here, you tell the cell to hide the Download button if the track is downloading.
Build and run your project. Download a few tracks concurrently and you’ll be able to pause, resume and cancel them at will:
Showing Download Progress
At this point, the app is functional, but it doesn’t show the progress of the download. To improve the user experience, you’ll change your app to listen for download progress events and display the progress in the cells. There’s a session delegate method that’s perfect for this job!
First, in TrackCell.swift, replace // TODO 16
with the following helper method:
func updateDisplay(progress: Float, totalSize : String) {
progressView.progress = progress
progressLabel.text = String(format: "%.1f%% of %@", progress * 100, totalSize)
}
The track cell has progressView
and progressLabel
outlets. The delegate method will call this helper method to set their values.
Next, in SearchViewController.swift, add the following delegate method to the URLSessionDownloadDelegate
extension:
func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask,
didWriteData bytesWritten: Int64, totalBytesWritten: Int64,
totalBytesExpectedToWrite: Int64) {
// 1
guard
let url = downloadTask.originalRequest?.url,
let download = downloadService.activeDownloads[url]
else {
return
}
// 2
download.progress =
Float(totalBytesWritten) / Float(totalBytesExpectedToWrite)
// 3
let totalSize =
ByteCountFormatter.string(fromByteCount: totalBytesExpectedToWrite,
countStyle: .file)
// 4
DispatchQueue.main.async {
if let trackCell =
self.tableView.cellForRow(at: IndexPath(row: download.track.index,
section: 0)) as? TrackCell {
trackCell.updateDisplay(progress: download.progress,
totalSize: totalSize)
}
}
}
Looking through this delegate method, step-by-step:
- You extract the URL of the provided
downloadTask
and use it to find the matchingDownload
in your dictionary of active downloads. - The method also provides the total bytes you have written and the total bytes you expect to write. You calculate the progress as the ratio of these two values and save the result in
Download
. The track cell will use this value to update the progress view. -
ByteCountFormatter
takes a byte value and generates a human-readable string showing the total download file size. You’ll use this string to show the size of the download alongside the percentage complete. - Finally, you find the cell responsible for displaying the
Track
and call the cell’s helper method to update its progress view and progress label with the values derived from the previous steps. This involves the UI, so you do it on the main queue.
Displaying the Download’s Progress
Now, update the cell’s configuration to display the progress view and status when a download is in progress.
Open TrackCell.swift. In configure(track:downloaded:download:)
, add the following line inside the if-closure, after the pause button title is set:
progressLabel.text = download.isDownloading ? "Downloading..." : "Paused"
This gives the cell something to show before the first update from the delegate method and while the download is paused.
Now, add the following code below the if-closure, below the isHidden
lines for the two buttons:
progressView.isHidden = !showDownloadControls
progressLabel.isHidden = !showDownloadControls
This shows the progress view and label only while the download is in progress.
Build and run your project. Download any track and you should see the progress bar status update as the download progresses:
Hurray, you’ve made, erm, progress! :]
Enabling Background Transfers
Your app is quite functional at this point, but there’s one major enhancement left to add: Background transfers.
In this mode, downloads continue even when your app is in the background or if it crashes for any reason. This isn’t really necessary for song snippets, which are pretty small, but your users will appreciate this feature if your app transfers large files.
But how can this work if your app isn’t running?
The OS runs a separate daemon outside the app to manage background transfer tasks, and it sends the appropriate delegate messages to the app as the download tasks run. In the event that the app terminates during an active transfer, the tasks will continue to run, unaffected, in the background.
When a task completes, the daemon will relaunch the app in the background. The relaunched app will recreate the background session to receive the relevant completion delegate messages and perform any required actions, such as persisting downloaded files to disk.
You’ll access this magic by creating a session with the background session configuration.
In SearchViewController.swift, in the initialization of downloadsSession
, find the following line of code:
let configuration = URLSessionConfiguration.default
…and replace it with the following line:
let configuration =
URLSessionConfiguration.background(withIdentifier:
"com.raywenderlich.HalfTunes.bgSession")
Instead of using a default session configuration, you’ll use a special background session configuration. Note that you also set a unique identifier for the session to allow your app to create a new background session, if needed.
Relaunching Your App
If a background task completes when the app isn’t running, the app will relaunch in the background. You’ll need to handle this event from your app delegate.
Switch to AppDelegate.swift, replace // TODO 17
with the following code:
var backgroundSessionCompletionHandler: (() -> Void)?
Next, replace // TODO 18
with the following method:
func application(
_ application: UIApplication,
handleEventsForBackgroundURLSession
handleEventsForBackgroundURLSessionidentifier: String,
completionHandler: @escaping () -> Void) {
backgroundSessionCompletionHandler = completionHandler
}
Here, you save the provided completionHandler
as a variable in your app delegate for later use.
application(_:handleEventsForBackgroundURLSession:)
wakes up the app to deal with the completed background task. You’ll need to handle two items in this method:
- First, the app needs to recreate the appropriate background configuration and session using the identifier provided by this delegate method. But since this app creates the background session when it instantiates
SearchViewController
, you’re already reconnected at this point! - Second, you’ll need to capture the completion handler provided by this delegate method. Invoking the completion handler tells the OS that your app’s done working with all background activities for the current session. It also causes the OS to snapshot your updated UI for display in the app switcher.
The place to invoke the provided completion handler is urlSessionDidFinishEvents(forBackgroundURLSession:)
, which is a URLSessionDelegate
method that fires when all tasks on the background session have finished.
In SearchViewController.swift replace // TODO 19
with the following extension:
extension SearchViewController: URLSessionDelegate {
func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
DispatchQueue.main.async {
if let appDelegate = UIApplication.shared.delegate as? AppDelegate,
let completionHandler = appDelegate.backgroundSessionCompletionHandler {
appDelegate.backgroundSessionCompletionHandler = nil
completionHandler()
}
}
}
}
The code above grabs the stored completion handler from the app delegate and invokes it on the main thread. You find the app delegate by getting the shared instance of UIApplication
, which is accessible thanks to the UIKit import.
Testing Your App’s Functionality
Build and run your app. Start a few concurrent downloads and tap the Home button to send the app to the background. Wait until you think the downloads have completed, then double-tap the Home button to reveal the app switcher.
The downloads should have finished, and you should see their new status in the app snapshot. Open the app to confirm this:
You now have a functional music-streaming app! Your move now, Apple Music! :]
Where to Go From Here?
Congratulations! You’re now well-equipped to handle most common networking requirements in your app.
If you want to explore the subject further, there are more URLSession
topics than would fit in this tutorial. For example, you can also try out uploading tasks and session configuration settings such as timeout values and caching policies.
To learn more about these features (and others!), check out the following resources:
- Apple’s URLSession Programming Guide contains comprehensive information on everything you’d want to do.
- Our own Networking with URLSession video course starts with HTTP basics, then goes on to cover tasks, background sessions, authentication, App Transport Security, architecture and unit testing.
- AlamoFire is a popular third-party iOS networking library; we cover the basics of it in our Beginning Alamofire tutorial.
I hope you enjoyed reading this tutorial. If you have any questions or comments, please join the discussion below!