iOS
Android
JavaScript

Using the Chooser

The Chooser is the fastest way to get files from Dropbox into your iOS app. It's a small framework 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 on iOS.

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

Download iOS SDKVersion 1.2.1, updated February 11, 2014Download

The iOS Chooser SDK zip contains DBChooser.framework and DBChooser.bundle.

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

Adding the Chooser SDK to your project

Open your project in Xcode.
Navigate to where you downloaded the SDK and drag the DBChooser.framework and DBChooser.bundle folders into your project in Xcode.
A confirmation dialog will pop up. Make sure Copy items ... is selected, then press Finish.

Creating a URL scheme

The Chooser coordinates with the Dropbox app to allow the user to select files without having to worry about the usual authorization flow. But in order to smoothly hand the user back to your app, you need to add a unique URL scheme that Dropbox can call. You'll need to configure your project to add one:

Click on your project in the Project Navigator, select the Target option on the left, choose the Info tab, expand the URL Types section at the bottom, and press the + button.
In the URL Schemes enter db-APP_KEY (replacing APP_KEY with the key generated when you created your app).

Example app

The iOS Chooser SDK zip also contains a ChooserExample Xcode 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 uses a didPressChooser IBAction to your view controller to trigger the Chooser. You'll need to connect it to a button in Interface Builder.

This example requests a preview link type using DBChooserLinkTypePreview which is explained more in the Link types section below.

Your top view controller

#import <DBChooser/DBChooser.h>

- (void)didPressChoose
{
    [[DBChooser defaultChooser] openChooserForLinkType:DBChooserLinkTypePreview
                                    fromViewController:self completion:^(NSArray *results)
    {
        if ([results count]) {
            // Process results from Chooser
        } else {
            // User canceled the action
        }
    }];
}

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 -application:openURL:sourceApplication:annotation: in your AppDelegate:

YourAppDelegate.m

#import <DBChooser/DBChooser.h>

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url
    sourceApplication:(NSString *)source annotation:(id)annotation
{

    if ([[DBChooser defaultChooser] handleOpenURL:url]) {
        // This was a Chooser response and handleOpenURL automatically ran the
        // completion block
        return YES;
    }

    return NO;
}

That's it! The handleOpenURL: hook will call the completion block when control returns to your app. Now you can handle the results parameter of the completion block.

Handling the response

The results parameter passed to the completion block will be an NSArray of DBChooserResult objects, each containing info about the selected file. Currently, the array will contain a single DBChooserResult object. If the user cancels the Chooser, the results parameter will be nil.

@interface DBChooserResult : NSObject

// URL to access the file, which varies depending on the link type specified when the
// Chooser was triggered
@property NSURL *link;

// Name of the file
@property NSString *name;

// Size of the file in bytes
@property long long size;

// URL to a 64x64px icon for the file based on the file's extension.
@property NSURL *iconURL;

// Set of thumbnail URLs generated when the user selects images and videos. It returns
// three sizes with the keys: 64x64px, 200x200px, and 640x480px. If the user didn't
// select an image or video, no thumbnails will be included.
@property NSDictionary *thumbnails;

@end

Link types

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

DBChooserLinkTypePreviewlinks 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.
DBChooserLinkTypeDirectlinks 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. These URLs should not be used to display content directly in the browser.

Handling multiple app keys

The example uses the defaultChooser, which is created and initialized with the URL Scheme you registered during setup. You may have a project that requires multiple app keys because it also uses another Dropbox API. In this case, you'll need to explicitly initialize your own instance of the Chooser with the right app key by using the -initWithAppKey: method.

Choose a language