Thomas Sillmann

Eine häufig gestellte Anforderung in der iOS-Entwicklung ist das Einrichten einer Dropbox-Synchronisation. Der gleichnamige Online-Dienst Dropbox hat sich als verlässlicher Online-Speicher etabliert und ist weit verbreitet. Und dank eines eigens bereitgestellten Frameworks vonseiten des Herstellers fällt es auch nicht schwer, diesen Service in die eigene App zu implementieren. Was genau zu tun ist soll hier nun erläutert werden.

Oberflächliches

Zuoberst steht - falls noch nicht vorhanden - das Einrichten eines eigenen Dropbox-Accounts. Dieser kann auf der Website des Herstellers unter http://www.dropbox.com/ kostenlos erstellt werden.

Der nächste Schritt besteht in der Registrierung der eigenen App auf der Entwicklerwebsite von Dropbox unter http://www.dropbox.com/developers/. Im Menü auf der rechten Seite findet sich der Punkt "My apps". Dort werden alle vom Entwickler für die Dropbox-Synchronisation eingerichteten Apps aufgelistet. Auch verfügt diese Seite über einen Button "Create an App", um eine neue App hinzuzufügen.

Nach Klick auf diese Schaltfläche muss der Entwickler erste Angaben zur App machen. Dabei handelt es sich um Folgendes:

• App name: Der Name der App
• Desricption: Beschreibung der App (quasi das Äquivalent zu der Beschreibung aus iTunes Connect)
• Access level: Das Access-Level bestimmt, welche Zugriffsrechte die App auf die Dropbox der Benutzer besitzt. Zur Wahl stehen "App folder" (empfohlen) und "Full dropbox". Beim "App folder" steht der App ein eigener Ordner für den Zugriff auf die Dropbox zur Verfügung (auf andere Bereiche innerhalb der Dropbox kann die App nicht zugreifen), mit "Full dropbox" erhält die App Vollzugriff auf die gesamte Dateistruktur. Sofern nicht anders benötigt wird empfohlen, der App einen eigenen Bereich innerhalb der Dropbox mittels "App folder" zuzuweisen.

Nach Eingabe dieser Informationen wird die App mittels Klick auf "Create" erstellt und der Entwickler auf eine weitere Bearbeitungsmaske weitergeleitet. Diese Maske ist ab diesem Zeitpunkt auch jederzeit erneut über den Menüpunkt "My apps" auf der Dropbox-Entwicklerseite abrufbar. Neben weiteren Angaben wie einer Website zur App, dem Namen des Entwicklers oder das Hochladen des App-Icons enthält diese Seite auch zwei für den Entwickler wichtige Angaben: Den "App key" und das "App secret". Diese beiden müssen im Quellcode des eigenen Projekts angegeben werden damit Dropbox weiß, mit welcher App er sich bei der Synchronisation verbindet. Während Sie also die Dropbox-Synchronisation in Ihrer Anwendung einrichten sollten Sie diese beiden Werte griffbereit halten.

In den Quellcode

Nach diesen Vorarbeiten auf der Dropbox-Website geht es nun in den Quellcode Ihres Projekts. Damit Sie überhaupt Zugriff auf die Dropbox erhalten müssen Sie zunächst das Dropbox-Framework für iOS herunterladen und in Ihr bestehendes Xcode-Projekt einbinden. Das aktuelle Dropbox-SDK erhalten Sie unter https://www.dropbox.com/developers/reference/sdk/. Die Einbindung des Frameworks in Ihr Projekt erfolgt unter Xcode 4 wie folgt:

• Öffnen Sie die Projekteinstellungen
• Wählen Sie unter "Targets" Ihre App aus
• Navigieren Sie zum Reiter "Build Phases"
• Öffnen Sie dort den Abschnitt "Link Binary With Libraries"
• Klicken Sie unten auf das "+"-Icon und wählen Sie das Dropbox-SDK von der Festplatte

Unter Xcode 3 kann das Framework einfach per Rechtsklick auf den Ordner "Frameworks" und anschließender Auswahl von "Add" -> "Existing Frameworks" dem Projekt hinzugefügt werden.

Sobald das Framework eingebunden ist gilt es, die Implementierungsdatei des AppDelegate zu öffnen. Zunächst müssen Sie die Dropbox-Klasse importieren, um auf deren Funktionen zugreifen zu können:

#import "DropboxSDK/DropboxSDK.h"

Anschließend binden Sie folgenden Code in die Methode application:didFinishLaunchingWithOptions: ein:

DBSession* dbSession = [[[DBSession alloc] initWithAppKey:@"APP_KEY" appSecret:@"APP_SECRET" root:ACCESS_TYPE] autorelease];
[DBSession setSharedSession:dbSession];

Damit wird die Verbindung zwischen Ihrer App und der Dropbox hergestellt. Zu diesem Zweck müssen Sie anstelle von APP_KEY und APP_SECRET die entsprechenden Werte Ihrer App aus dem Dropbox-Entwicklerportal eingeben. ACCESS_TYPE ersetzen Sie entweder durch kDBRootAppFolder (falls Sie als Access level Ihrer App "App folder" eingegeben haben) oder kDBRootDropbox (falls das Access level auf "Full dropbox" eingestellt ist).

Um nun die Verbindung mit der Dropbox herzustellen, muss an der entsprechenden Stelle im Quellcode folgende if-Abfrage eingefügt werden:

if (![[DBSession sharedSession] isLinked]) {
    [[DBSession sharedSession] link];
}

Diese Abfrage überprüft, ob die App vom Benutzer bereits mit seinem Dropbox-Account verknüpft wurde. Falls nein, wird (sofern installiert) der Dropbox-Client oder der Webbrowser Safari gestartet. In diesem Schritt wird dem Nutzer dann eine Info angezeigt, dass die entsprechende App gerne auf die Dropbox zugreifen möchte. Erst wenn der Nutzer dies bestätigt kann er auch mittels Ihrer App auf die eigene Dropbox zugreifen.

Wurde die App einmalig in diesem Schritt für Dropbox authentifiziert, startet die App daraufhin nun mit dem URL-Scheme db-APP_KEY; diesen müssen Sie nun noch Ihrer Anwendung hinzufügen (und dabei natürlich APP_KEY durch Ihren eigenen Schlüssel ersetzen). Rufen Sie zu diesem Zweck Ihre "Info.plist"-Datei auf, öffnen diese in der Quellcode-Ansicht (Rechtsklick, "Open As" -> "Source Code") und fügen folgenden Abschnitt hinzu:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>db-APP_KEY</string>
        </array>
    </dict>
</array>

Nach diesen Arbeiten fehlt nur noch eine Methode, um die Dropbox-Authentifizierung mit Ihrer eigenen App abzuschließen. Dazu muss erneut die Implementierungsdatei des AppDelegate aufgerufen und folgende Methode hinzugefügt werden:

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url {
    if ([[DBSession sharedSession] handleOpenURL:url]) {
        if ([[DBSession sharedSession] isLinked]) {
            NSLog(@"App linked successfully!");
            // At this point you can start making API calls
        }
        return YES;
    }
    // Add whatever other url handling code your app requires here
    return NO;
}

Anschließend kann es an einen ersten Test gehen: Starten Sie Ihre App und rufen Sie die Stelle zur Verbindung mit der Dropbox auf. Nun sollte sich entweder der Dropbox-Client oder der Safari-Browser öffnen und Sie darauf hinweisen, dass Ihre App Zugriff auf die Dropbox möchte. Wenn Sie das zulassen und anschließend wieder in Ihrer App landen funktioniert soweit alles einwandfrei! Nun geht es in diesem Tutorial noch darum, eine Datei in die Dropbox hochzuladen.

Hochladen einer Datei nach Dropbox

Dies ist der wohl häufigste Einsatzzweck der Dropbox unter iOS: Bearbeitete Dateien innerhalb der eigenen App sollen zur weiteren Bearbeitung (zum Beispiel am eigenen Rechner) in die Dropbox hochgeladen werden, um sie von dort aus von jedem anderen Gerät wieder abrufen zu können.

Nachdem oben genannte Schritte alle erfolgreich abgeschlossen wurden und Ihre App erfolgreich mit Dropbox gekoppelt wurde geht es nun darum, eine in der App hinterlegte Datei in die Dropbox hochzuladen. Zu diesem Zweck muss zunächst eine Instanzvariable der Klasse DBRestClient erstellt werden; diese ermöglicht nach der Verlinkung Ihrer App mit der Dropbox die Kommunikation mit derselbigen.

Fügen Sie darum in die Header-Datei der Klasse, in der Sie den Dropbox-Aufruf durchführen möchten, folgende Zeile hinzu:

DBRestClient *restClient;

Damit haben Sie eine Instanzvariable mit dem Namen restClient erstellt. Diese müssen Sie nun noch in der entsprechenden Implementierungsdatei initialisieren. Fügen Sie zu diesem Zweck folgende Methode der Implementierungsdatei hinzu:

- (DBRestClient *)restClient {
   if (!restClient) {
      restClient = [[DBRestClient alloc] initWithSession:[DBSession sharedSession]];
      restClient.delegate = self;
   }
   return restClient;
}

Nun können Sie mit der Variable restClient auf Ihre Dropbox zugreifen. Das Hochladen einer Datei erfolgt dabei über folgenden Befehl:

[[self restClient] uploadFile:filename toPath:destDir withParentRev:nil fromPath:localPath];

Insgesamt werden hier drei Parameter übergeben:

• fileName: Der Name der Datei, die in die Dropbox hochgeladen wird
• destDir: Das Verzeichnis innerhalb der Dropbox, in welches die Datei gesichert werden soll.
• localPath: Der Pfad zur Datei innerhalb der eigenen iOS-App

Bei diesen drei Parametern handelt es sich um Variablen vom Typ NSString. Um einmal zu testen, ob die Funktion korrekt arbeitet, können Sie einmal beim Aufruf Ihrer Dropbox-Funktion folgenden Code übergeben:

NSString *localPath = [[NSBundle mainBundle] pathForResource:@"Info" ofType:@"plist"];
NSString *filename = @"Info.plist";
NSString *destDir = @"/";
[[self restClient] uploadFile:filename toPath:destDir withParentRev:nil fromPath:localPath];

Hat alles geklappt sollte die Info.plist sich nun in Ihrem Dropbox-Verzeichnis befinden!

Erfolg oder Misserfolg des Uploads auswerten

Zum Abschluss dieses kleinen Tutorials sei noch auf zwei Methoden hingewiesen die vom SDK nach Anstoßen des Uploads automatisch aufgerufen werden und Rückmeldung geben, ob der Upload erfolgreich war oder nicht:

//Upload successful
- (void)restClient:(DBRestClient*)client uploadedFile:(NSString*)destPath from:(NSString*)srcPath metadata:(DBMetadata*)metadata {
    NSLog(@"File uploaded successfully to path: %@", metadata.path);
}

//Upload failed
- (void)restClient:(DBRestClient*)client uploadFileFailedWithError:(NSError*)error {
    NSLog(@"File upload failed with error - %@", error);
}

Je nachdem, ob der Upload geklappt hat oder nicht, wird entweder die oben oder unten aufgeführte Methode ausgeführt. Hier kann der Entwickler entsprechend entweder eine Erfolgsmeldung ausgeben oder den Fehler anhand der übergebenen error-Variable auswerten.