Using the Saver

The Saver is the easiest way to add files to your users' Dropboxes. With two clicks, a user can download files of any size into their Dropbox, making those files available on all their computers and devices as soon as the download completes. The Saver is a Drop-in component that works on web and mobile web—all with just a few lines of code.

Demo

Click the button below to see the Saver in action. The demo triggers the Saver in a pop-up window and will ask you to sign in if you haven't already. By default, files will be saved to a new Saves folder in Dropbox, but you can select an alternate destination as well. Once you press the Save button, the files are downloaded and saved to your Dropbox.

Setup

The first step in adding the Saver is to create a Drop-in app. Drop-in apps don't require the production approval step that other Dropbox apps do. You can publish your integration to your users as soon as you're ready.

When you create a Saver app for the web, you'll need to provide the domain names where your app is hosted. This lets us stop other websites from trying to impersonate your app. If you're developing locally, you can use localhost as the domain name as well.

Once you've created a new app, add the following JavaScript snippet to your HTML. Use the pull-down menu below to select your Dropbox app and the app key will be pre-filled for you.

to see your apps or create a new app.

Generic embed code (insert your app key)

<script type="text/javascript" src="https://www.dropbox.com/static/api/2/dropins.js" id="dropboxjs" data-app-key="YOUR_APP_KEY"></script>

Saver button

The easiest way to add the Saver to your app is to change a simple link to a Saver button. You can turn any <a> tag into a Saver button just by adding class="dropbox-saver" to it. You can see this below:

<a href="https://dl.dropboxusercontent.com/s/deroi5nwm6u7gdf/advice.png" class="dropbox-saver"></a>

The button takes in the following parameters:

class Identifies the anchor element as a Saver button. Must have the value `dropbox-saver`.
href URL of the file the Saver should add to the user's Dropbox. The Saver supports HTTP and HTTPS URIs.
data-filename optional User-friendly name of the file that should be saved to the user's Dropbox can be included if desired. If not included, the filename is inferred from the `href`.

Programmatically creating Saver buttons

Adding the dropbox-saver class to an existing anchor tag is easy if you just need to allow users to save a hardcoded URL. For more dynamic uses, though, you may prefer to create a Save button programmatically by calling Dropbox.createSaveButton.

var options = {
    files: [
        // You can specify up to 100 files.
        {'url': '...', 'filename': '...'},
        {'url': '...', 'filename': '...'},
        // ...
    ],

    // Success is called once all files have been successfully added to the user's
    // Dropbox, although they may not have synced to the user's devices yet.
    success: function () {
        // Indicate to the user that the files have been saved.
        alert("Success! Files saved to your Dropbox.");
    },

    // Progress is called periodically to update the application on the progress
    // of the user's downloads. The value passed to this callback is a float
    // between 0 and 1. The progress callback is guaranteed to be called at least
    // once with the value 1.
    progress: function (progress) {},

    // Cancel is called if the user presses the Cancel button or closes the Saver.
    cancel: function () {},

    // Error is called in the event of an unexpected response from the server
    // hosting the files, such as not being able to find a file. This callback is
    // also called if there is an error on Dropbox or if the user is over quota.
    error: function (errorMessage) {}
};
var button = Dropbox.createSaveButton(options);
document.getElementById("container").appendChild(button);

If you're only saving one file, you can use the following shortcut:

Dropbox.createSaveButton(url, filename, options);

The filename parameter can always be omitted, in which case the filename in the URL will be used. You should indicate to the user that the file(s) have been successfully saved to their Dropbox using the success option. Note that these methods may modify the options object but it's safe to reuse for subsequent calls.

Triggering the Saver from JavaScript

If you prefer to design a custom button and trigger the Saver, you can trigger the Saver directly from JavaScript by using the following method:

var options = { /* Same options as above ... */ };
Dropbox.save(options);

If you're only saving one file, you can use the following shortcut:

var options = { /* Same options as above ... */ };
Dropbox.save(url, filename, options);

Note that the Saver opens in a pop-up window, so you should only call this function from within a user-triggered event handler such as a tap or click event. Otherwise, the pop-up will likely be blocked by the browser.

How the Saver handles caching

A major benefit of the Saver is that we cache your files on our servers, which reduces your bandwidth costs. We only download unique files from your servers once. After that, we cache on our servers. Saver respects HTTP 1.1's caching controls, storing both freshness and validation info for the URLs you provide. The following section provides details around the appropriate cache headers you can include to enable this.

Freshness

When Dropbox requests the URLs you pass to the Saver, it will examine the Cache-Control and Expires HTTP headers you include with the response. If a user saves a file that hasn't yet expired according to these caching headers, Dropbox will just use the cached file and not hit your server.

Validation

Validation is determined by the ETag and Last-Modified HTTP headers that your server sends when Dropbox downloads the file at the URL. When Dropbox determines that our cached copy is invalid, it will send a request to your server with two validation headers: If-None-Match, which includes the Etag of the file we have cached, and If-Modified-Since, which includes the last modified time of the file we have cached. If your server responds with a 304, Dropbox will continue to use the cached version of the file as well as update the freshness HTTP headers (if given).

Supported browsers

Not all browsers support the Saver. If a user's browser doesn't support the Saver, we'll gray out the button and show a warning message if you try to call Dropbox.save(). You can check to see if the user's browser is supported by calling Dropbox.isBrowserSupported().

The Saver supports the following browsers:

Desktop

Internet Explorer, versions 9+
Chrome
Firefox
Safari

Mobile

Safari
Android browser
Chrome on Android

Contents

Choose a language