Using the Chooser

The Chooser is the fastest way to get files from Dropbox into your Android app. It's a small library that enables your app to access files from Dropbox without having to worry about the complexities of implementing a file browser, OAuth, or managing uploads and storage. Take a look at a screenshot of what the Chooser looks like inside an Android app.

This tutorial will guide you through everything you need to do to add the Chooser to your app and customize it to suit your use cases.

Setup

The Android Chooser SDK zip contains a DropboxChooserSDK Android library project. You'll need to add this to Eclipse and then reference it in your project.

You'll also need to create a new Drop-in app in the App Console if you haven't already as you'll need the App key below.

Creating the new project

  1. Open Eclipse, go to File → New → Other → Android → Android Project from Existing Code and press Next
  2. Press Browse next to the Root Directory field and select the DropboxChooserSDK folder you just unzipped. Press Finish.
  3. You should now have a DropboxChooserSDK project.

Referencing the project

  1. In Eclipse, right click on your existing project and click Properties.
  2. In the menu on the left hand side, select Android.
  3. In the lower Library section, click Add and select the DropboxChooserSDK project.

Example app

The Android Chooser SDK zip also contains a ChooserExample Android app project that implements an expanded version of the code below. Open it and follow along with the rest of this guide.

Triggering the Chooser

Your app should give the user a button or action that asks them to select a file from Dropbox. This example sets up a click handler in onCreate() for a button called chooser_button that will trigger the Chooser. You'll need to add a button with the same name to your layout as well.

In this example, we'll request a preview link type using DbxChooser.ResultType.PREVIEW_LINK (read more about link types below). This example also uses an Activity but it works just as well with a Fragment.

Be sure to replace APP_KEY with the real value for your app.
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;
import com.dropbox.chooser.android.DbxChooser;

static final int DBX_CHOOSER_REQUEST = 0;  // You can change this if needed

private Button mChooserButton;
private DbxChooser mChooser;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mChooser = new DbxChooser(APP_KEY);

    mChooserButton = (Button) findViewById(R.id.chooser_button);
    mChooserButton.setOnClickListener(new OnClickListener() {
        @Override
        public void onClick(View v) {
            mChooser.forResultType(DbxChooser.ResultType.PREVIEW_LINK)
                    .launch(MainActivity.this, DBX_CHOOSER_REQUEST);
        }
    });
}

The Chooser coordinates with the Dropbox app to allow the user to select files without having to worry about the usual authorization flow. In order to handle the response when the user returns to your app, you'll need to add a hook to onActivityResult():

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == DBX_CHOOSER_REQUEST) {
        if (resultCode == Activity.RESULT_OK) {
            DbxChooser.Result result = new DbxChooser.Result(data);
            Log.d("main", "Link to selected file: " + result.getLink());

            // Handle the result
        } else {
            // Failed or was cancelled by the user.
        }
    } else {
        super.onActivityResult(requestCode, resultCode, data);
    }
}

If the user cancels, resultCode will be Activity.RESULT_CANCELED. A successful choice will be Activity.RESULT_OK. In the case of a successful choice, you can create a new DbxChooser.Result to handle the response.

Handling the response

The DbxChooser.Result created in the onActivityResult() callback will contain the info about the selected file.

public static class Result {

    // URI to access the file, which varies depending on the link type specified when
    // the Chooser was triggered
    public Uri getLink() { ... }

    // Name of the file
    public String getName() { ... }

    // URI to a 64px x 64px icon for the file based on the file's extension
    public Uri getIcon() { ... }

    // Size of the file in bytes
    public long getSize() { ... }

    // Set of thumbnail URIs generated when the user selects images and videos. It
    // returns three sizes: 64x64px, 200x200px, and 640x480px. If the user didn't
    // select an image or video, no thumbnails will be included.
    public Map<String, Uri> getThumbnails() { ... }

}

The Chooser can be configured to return one of three link types.

  • ResultType.PREVIEW_LINKlinks are the default type of link returned by the Chooser. Preview links point to a human-friendly preview page of a file and are great for sharing. You can read more about links to Dropbox files in our Help Center. Note that users may disable this link at a later point if they choose.

  • ResultType.DIRECT_LINKlinks point directly to the contents of the file and are useful for downloading the file itself. Unlike preview links, however, they will expire after four hours, so make sure to download the contents of the file immediately after the file is chosen.

  • ResultType.FILE_CONTENTlinks (Android only) point to the actual file on the local device and let your app take advantage of files cached by the Dropbox app. However, these files are temporary and can be cleaned up by the operating system at any point, so you should copy it and manage it within your app if you need to keep the contents of a file.

Android API support

The Android Chooser SDK includes the Android Support Library and is written to support Android API version 8 and higher. To support Android API versions 8, 9, and 10, your app must extend Activity or android.support.v4.app.FragmentActivity instead of Fragment. If it doesn't, you'll see the following error in LogCat when using the Android Chooser on these older versions:

The Chooser requires Fragments. If below API level 11, pass in a FragmentActivity from the support library.

Also, the Android Support Library that is bundled with the Chooser may conflict with the support library in your project if your project has a different version. If you see a "Jar mismatch! Fix your dependencies" error in the Console, delete android-support-v4.jar in the libs directory of DropboxChooserSDK and copy the version of android-support-v4.jar from your project into that folder.