Download Files with Cloud Storage for Unity

Cloud 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 Cloud 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 Cloud Storage.

// Create a reference with an initial file path and name
Firebase.Storage.StorageReference path_reference =
  storage.GetReference("images/stars.jpg");

// Create a reference from a Google Cloud Storage URI
Firebase.Storage.StorageReference gs_reference =
  storage.GetReferenceFromUrl("gs://bucket/images/stars.jpg");

// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
Firebase.Storage.StorageReference https_reference =
  storage.GetReferenceFromUrl("https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg");

Download Files

Files stored in Cloud Storage can be retrieved in four ways:

1. Download from a URL
2. Download to a byte array
3. Download with a Stream
4. Download to a local file

The method you will use to retrieve your files will depend on how you want to consume the data in your game.

Download from a URL

If you want to use a URL with Unity's WWW or UnityWebRequest you can get a download URL for a file by calling GetDownloadUrlAsync().

// Fetch the download URL
reference.GetDownloadUrlAsync().ContinueWith((Task<Uri> task) => {
  if (!task.IsFaulted && !task.IsCanceled) {
    Debug.Log("Download URL: " + task.Result());
    // ... now download the file via WWW or UnityWebRequest.
  }
});

Download to a byte array

You can download the file to a byte buffer in memory using the GetBytesAsync() method. This method will load the 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.

// Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes)
const long maxAllowedSize = 1 * 1024 * 1024;
reference.GetBytesAsync(maxAllowedSize).ContinueWith((Task<byte[]> task) => {
  if (task.IsFaulted || task.IsCanceled) {
    Debug.Log(task.Exception.ToString());
    // Uh-oh, an error occurred!
  } else {
    byte[] fileContents = task.Result;
    Debug.Log("Finished downloading!");
  }
});

Download via a Stream

Downloading the file with a Stream allows you to process the data as its loaded. This gives you maximum flexibility when dealing with your download. Call GetStreamAsync() and pass your own stream processor as the first argument. This delegate will get called on a background thread with a Stream which allows you to perform latency intensive operations or calculations such as storing the contents to disk.

// Download via a Stream
reference.GetStreamAsync( stream => {
    // Do something with the stream here.
    //
    // This code runs on a background thread which reduces the impact
    // to your framerate.
    //
    // If you want to do something on the main thread, you can do that in the
    // progress eventhandler (second argument) or ContinueWith to execute it
    // at task completion.
}, null, CancellationToken.None);

GetStreamAsync() takes an optional arguments after the stream processor that allows you to cancel the operation or get notified of progress.

Download to a local file

The GetFileAsync() 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 the file in a different app.

// Create local filesystem URL
string local_url = "file:///local/images/island.jpg";

// Download to the local filesystem
reference.GetFileAsync(local_url).ContinueWith(task => {
    if (!task.IsFaulted && !task.IsCanceled) {
        Debug.Log("File downloaded.");
    }
});

You can attach listeners to downloads in order to monitor the progress of the download. The listener follows the standard System.IProgress<T> interface. You can use an instance of the StorageProgress class, to provide your own Action<T> as a callback for progress ticks.

// Create local filesystem URL
string local_url = "file:///local/images/island.jpg";

// Start downloading a file
Task task = reference.GetFileAsync(local_file,
  new Firebase.Storage.StorageProgress <DownloadState>((DownloadState state) => {
    // called periodically during the download
    Debug.Log(String.Format(
      "Progress: {0} of {1} bytes transferred.",
      state.BytesTransferred,
      state.TotalByteCount
    ));
  }), CancellationToken.None);

task.ContinueWith(resultTask => {
  if (!resultTask.IsFaulted && !resultTask.IsCanceled) {
    Debug.Log("Download finished.");
  }
});

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.

Next Steps

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