Download files with Cloud Storage for Unity

This page describes how to use the Cloud Storage for Firebase SDK to download files from a Cloud Storage bucket.

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 root of your Cloud Storage bucket, 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
StorageReference pathReference =
    storage.GetReference("images/stars.jpg");

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

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

Download files

Once you have a reference, you can download files from Cloud Storage 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().ContinueWithOnMainThread(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 loads 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).ContinueWithOnMainThread(task => {
    if (task.IsFaulted || task.IsCanceled) {
        Debug.LogException(task.Exception);
        // Uh-oh, an error occurred!
    }
    else {
        byte[] fileContents = task.Result;
        Debug.Log("Finished downloading!");
    }
});

Download via a stream

Downloading the file with a Stream lets you process the data as it's 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 lets you 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 argument after the stream processor that lets you 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 localUrl = "file:///local/images/island.jpg";

// Download to the local filesystem
reference.GetFileAsync(localUrl).ContinueWithOnMainThread(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 localUrl = "file:///local/images/island.jpg";

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

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

Error handling

There are a number of reasons why errors might occur on download, including the file not existing, or the user not having permission to access the intended file. For more information about errors, see Handle errors.

Next steps

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