Download Files on iOS

Firebase Storage allows developers to quickly and easily download files from a Google Cloud Storage bucket provided and managed by Firebase.

Create a Reference

To download a file, first create a Firebase Storage reference to the file you want to download.

You can create a reference by appending child paths to the storage root, or you can create a reference from an existing gs:// or https:// URL referencing an object in Firebase Storage.

// Create a reference with an initial file path and name
FIRStorageReference *pathReference = [storage referenceWithPath:@"images/stars.jpg"];

// Create a reference from a Google Cloud Storage URI
FIRStorageReference *gsReference = [storage referenceForURL:@"gs://bucket/images/stars.jpg"];

// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
FIRStorageReference *httpsReference = [storage referenceForURL:@"https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg"];
  

// Create a reference with an initial file path and name
let pathReference = storage.reference("images/stars.jpg")

// Create a reference from a Google Cloud Storage URI
let gsReference = storage.referenceForURL('gs://bucket/images/stars.jpg')

// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
let httpsReference = FIRStorage.storage().referenceForURL('https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg')

Download Files

Once you have a reference, you can download files from Firebase Storage in three ways:

1. Download to NSData in memory
2. Download to an NSURL representing a file on device
3. Generate an NSURL representing the file online

Download in memory

Download the file to an NSData object in memory using the dataWithMaxSize:completion: method. This is the easiest way to quickly download a file, but it must load entire contents of your file into memory. If you request a file larger than your app's available memory, your app will crash. To protect against memory issues, make sure to set the max size to something you know your app can handle, or use another download method.

// Create a reference to the file you want to download
FIRStorage *islandRef = [storageRef child:@"images/island.jpg"];

// Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes)
[islandRef dataWithMaxSize:1 * 1024 * 1024 completion:^(NSData *data, NSError *error){
  if (error != nil) {
    // Uh-oh, an error occurred!
  } else {
    // Data for "images/island.jpg" is returned
    // ... UIImage *islandImage = [UIImage imageWithData:data];
  }
}];
    

// Create a reference to the file you want to download
let islandRef = storageRef.child("images/island.jpg")

// Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes)
islandRef.dataWithMaxSize(1 * 1024 * 1024) { (data, error) -> Void in
  if (error != nil) {
    // Uh-oh, an error occurred!
  } else {
    // Data for "images/island.jpg" is returned
    // ... let islandImage: UIImage! = UIImage(data: data!)
  }
}
    

Download to a local file

The writeToFile:completion: method downloads a file directly to a local device. Use this if your users want to have access to the file while offline or to share in a different app. writeToFile:completion: returns an FIRStorageDownloadTask which you can use to manage your download and monitor the status of the upload.

// Create a reference to the file you want to download
FIRStorage *islandRef = [storageRef child:@"images/island.jpg"];

// Create local filesystem URL
NSURL *localURL = [NSURL URLWithString:@"file:///local/images/island.jpg"];

// Download to the local filesystem
FIRStorageDownloadTask *downloadTask = [islandRef writeToFile:localURL completion:^(NSURL *URL, NSError *error){
  if (error != nil) {
    // Uh-oh, an error occurred!
  } else {
    // Local file URL for "images/island.jpg" is returned
  }
}];
    

// Create a reference to the file you want to download
let islandRef = storageRef.child("images/island.jpg")

// Create local filesystem URL
let localURL: NSURL! = NSURL(string: "file:///local/images/island.jpg")

// Download to the local filesystem
let downloadTask = islandRef.writeToFile(localURL) { (URL, error) -> Void in
  if (error != nil) {
    // Uh-oh, an error occurred!
  } else {
    // Local file URL for "images/island.jpg" is returned
  }
}
    

If you want to actively manage your download, you can use the writeToFile: method and observe the download task, rather than use the completion handler. See Manage Downloads for more information.

Generate a download URL

If you already have download infrastructure based around URLs, or just want a URL to share, you can get the download URL for a file by calling the downloadURLWithCompletion: method on a storage reference.

// Create a reference to the file you want to download
FIRStorageReference *starsRef = [storageRef child:@"images/stars.jpg"];

// Fetch the download URL
[starsRef downloadURLWithCompletion:^(NSURL *URL, NSError *error){
  if (error != nil) {
    // Handle any errors
  } else {
    // Get the download URL for 'images/stars.jpg'
  }
}];
    

// Create a reference to the file you want to download
let starsRef = storageRef.child("images/stars.jpg")

// Fetch the download URL
starsRef.downloadURLWithCompletion { (URL, error) -> Void in
  if (error != nil) {
    // Handle any errors
  } else {
    // Get the download URL for 'images/stars.jpg'
  }
}
    

Manage Downloads

In addition to starting downloads, you can pause, resume, and cancel downloads using the pause, resume, and cancel methods. These methods raise pause, resume, and cancel events that you can observe.

// Start downloading a file
FIRStorageDownloadTask *downloadTask = [[storageRef child:@"images/mountains.jpg"] writeToFile:localFile];

// Pause the download
[downloadTask pause];

// Resume the download
[downloadTask resume];

// Cancel the download
[downloadTask cancel];
    

// Start downloading a file
let downloadTask = storageRef.child('images/mountains.jpg').writeToFile(localFile)

// Pause the download
downloadTask.pause()

// Resume the download
downloadTask.resume()

// Cancel the download
downloadTask.cancel()
    

Monitor Download Progress

You can attach observers to FIRStorageDownloadTasks in order to monitor the progress of the download. Adding an observer returns a FIRStorageHandle that can be used to remove the observer.

// Add a progress observer to a download task
FIRTaskListenerHandle observer = [downloadTask observeStatus:FIRStorageTaskStatusProgress
                                                     handler:^(FIRStorageTaskSnapshot *snapshot) {
  // A progress event occurred
}];
    

// Add a progress observer to a download task
let observer = downloadTask.observeStatus(.Progress) { (snapshot) -> Void in
  // A progress event occurred
}
    

These observers can be registered to an FIRStorageTaskStatus event:

When an event occurs, an FIRStorageTaskSnapshot object is passed back. This snapshot is an immutable view of the task, at the time the event occurred. This object contains the following properties:

You can also remove observers, either individually, by status, or by removing all of them.

// Create a task listener handle
FIRStorageHandle observer = ...

// Remove an individual observer
[downloadTask removeObserverWithHandle:observer];

// Remove all observers of a particular status
[downloadTask removeAllObserversForStatus:FIRStorageTaskStatusProgress];

// Remove all observers
[downloadTask removeAllObservers];
    

// Create a task listener handle
let observer = ...

// Remove an individual observer
downloadTask.removeObserverWithHandle(observer)

// Remove all observers of a particular status
downloadTask.removeAllObserversForStatus(.Progress)

// Remove all observers
downloadTask.removeAllObservers()
    

To prevent memory leaks, all observers are removed after an FIRStorageTaskStatusSuccess or FIRStorageTaskStatusFailure occurs.

Handle Errors

There are a number of reasons why errors may occur on download, including the file not existing, or the user not having permission to access the desired file. More information on errors can be found in the Handle Errors section of the docs.

Full Example

A full example of downloading to a local file with error handling is shown below:

// Create a reference to the file we want to download
FIRStorageReference *starsRef = [storageRef child@"images/stars.jpg"];

// Start the download (in this case writing to a file)
FIRStorageDownloadTask *downloadTask = [storageRef writeToFile:localURL];

// Observe changes in status
[downloadTask observeStatus:FIRStorageTaskStatusResume handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Download resumed, also fires when the download starts
}];

[downloadTask observeStatus:FIRStorageTaskStatusPause handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Download paused
}];

[downloadTask observeStatus:FIRStorageTaskStatusProgress handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Download reported progress
  double percentComplete = 100.0 * (snapshot.progress.completedUnitCount) / (snapshot.progress.totalUnitCount);
}];

[downloadTask observeStatus:FIRStorageTaskStatusSuccess handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Download completed successfully
}];

// Errors only occur in the "Failure" case
[downloadTask observeStatus:FIRStorageTaskStatusFailure handler:^(FIRStorageTaskSnapshot *snapshot) {
  if (snapshot.error != nil) {
    switch (snapshot.error.code) {
      case FIRStorageErrorCodeObjectNotFound:
        // File doesn't exist
        break;

      case FIRStorageErrorCodeUnauthorized:
        // User doesn't have permission to access file
        break;

      case FIRStorageErrorCodeCancelled:
        // User canceled the upload
        break;

      ...

      case FIRStorageErrorCodeUnknown:
        // Unknown error occurred, inspect the server response
        break;
    }
  }
}];
    

// Create a reference to the file we want to download
var starsRef = storageRef.child("images/stars.jpg")

// Start the download (in this case writing to a file)
let downloadTask = starsRef.writeToFile(localURL)

// Observe changes in status
downloadTask.observeStatus(.Resume) { (snapshot) -> Void in
  // Download resumed, also fires when the download starts
}

downloadTask.observeStatus(.Pause) { (snapshot) -> Void in
  // Download paused
}

downloadTask.observeStatus(.Progress) { (snapshot) -> Void in
  // Download reported progress
  let percentComplete = 100.0 * (snapshot.progress?.completedUnitCount)! / (snapshot.progress?.totalUnitCount)!
}

downloadTask.observeStatus(.Success) { (snapshot) -> Void in
  // Download completed successfully
}

// Errors only occur in the "Failure" case
downloadTask.observeStatus(.Failure) { (snapshot) -> Void in
  guard let storageError = snapshot.error else { return }
  guard let errorCode = FIRStorageErrorCode(rawValue: storageError.code) else { return }
  switch errorCode {
    case .ObjectNotFound:
      // File doesn't exist

    case .Unauthorized:
      // User doesn't have permission to access file

    case .Cancelled:
      // User canceled the upload

    ...

    case .Unknown:
      // Unknown error occurred, inspect the server response
  }
}
    

You can also get and update metadata for files that are stored in Firebase Storage.