SwiftyDropbox
Swift SDK for the Dropbox API v2.
Install / Use
/learn @dropbox/SwiftyDropboxREADME
Dropbox for Swift
Version 10.0.0 differs greatly from previous versions of the SDK. See Changes in version 10.0.0 and, if needed, Migrating from dropbox-sdk-obj-c.
The Official Dropbox Swift SDK for integrating with Dropbox API v2 on iOS or macOS.
Full documentation here.
Table of Contents
- System requirements
- Get started
- SDK distribution
- Configure your project
- Try some API requests
- Objective-C
- Changes in version 10.0.0
- Examples
- Documentation
- Stone
- Modifications
- App Store Connect Privacy Labels
- Bugs
System requirements
- iOS 12.0+
- macOS 10.13+
- Xcode 13.3+
- Swift 5.6+
Get Started
Register your application
Before using this SDK, you should register your application in the Dropbox App Console. This creates a record of your app with Dropbox that will be associated with the API calls you make.
Obtain an OAuth 2.0 token
All requests need to be made with an OAuth 2.0 access token. An OAuth token represents an authenticated link between a Dropbox app and a Dropbox user account or team.
Once you've created an app, you can go to the App Console and manually generate an access token to authorize your app to access your own Dropbox account. Otherwise, you can obtain an OAuth token programmatically using the SDK's pre-defined auth flow. For more information, see below.
SDK distribution
You can integrate the Dropbox Swift SDK into your project using one of several methods.
Swift Package Manager
The Dropbox Swift SDK can be installed in your project using Swift Package Manager by specifying the Dropbox Swift SDK repository URL:
https://github.com/dropbox/SwiftyDropbox.git
Refer to Apple's "Adding Package Dependencies to Your App" documentation for more information.
CocoaPods
To use CocoaPods, a dependency manager for Cocoa projects, you should first install it using the following command:
$ gem install cocoapods
Then navigate to the directory that contains your project and create a new file called Podfile. You can do this either with pod init, or open an existing Podfile, and then add pod 'SwiftyDropbox' to the main loop. Your Podfile should look something like this:
use_frameworks!
target '<YOUR_PROJECT_NAME>' do
pod 'SwiftyDropbox'
end
If your project contains Objective-C code that will need to have access to Dropbox SDK there is a separate pod called SwiftyDropboxObjC that contains an Objective-C compatibility layer for the SDK. Add this pod to your Podfile (in addition to SwiftyDropbox or on its own). For more information refer to the Objective-C section of this README.
Then, run the following command to install the dependency:
$ pod install
Once your project is integrated with the Dropbox Swift SDK, you can pull SDK updates using the following command:
$ pod update
Configure your project
Once you have integrated the Dropbox Swift SDK into your project, there are a few additional steps to take before you can begin making API calls.
Application .plist file
If you are compiling on iOS SDK 9.0, you will need to modify your application's .plist to handle Apple's new security changes to the canOpenURL function. You should
add the following code to your application's .plist file:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>dbapi-8-emm</string>
<string>dbapi-2</string>
</array>
This allows the Swift SDK to determine if the official Dropbox iOS app is installed on the current device. If it is installed, then the official Dropbox iOS app can be used to programmatically obtain an OAuth 2.0 access token.
Additionally, your application needs to register to handle a unique Dropbox URL scheme for redirect following completion of the OAuth 2.0 authorization flow. This URL scheme should have the format db-<APP_KEY>, where <APP_KEY> is your
Dropbox app's app key, which can be found in the App Console.
You should add the following code to your .plist file (but be sure to replace <APP_KEY> with your app's app key):
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>db-<APP_KEY></string>
</array>
<key>CFBundleURLName</key>
<string></string>
</dict>
</array>
After you've made the above changes, your application's .plist file should look something like this:
Handling the authorization flow
There are three methods to programmatically retrieve an OAuth 2.0 access token:
- Direct auth (iOS only): This launches the official Dropbox iOS app (if installed), authenticates via the official app, then redirects back into the SDK
- Safari view controller auth (iOS only): This launches a
SFSafariViewControllerto facillitate the auth flow. This is desirable because it is safer for the end-user, and pre-existing session data can be used to avoid requiring the user to re-enter their Dropbox credentials. - Redirect to external browser (macOS only): This launches the user's default browser to facillitate the auth flow. This is also desirable because it is safer for the end-user, and pre-existing session data can be used to avoid requiring the user to re-enter their Dropbox credentials.
To facilitate the above authorization flows, you should take the following steps:
Initialize a DropboxClient instance
From your application delegate:
SwiftUI note: You may need to create an Application Delegate if your application doesn't have one.
iOS
import SwiftyDropbox
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
DropboxClientsManager.setupWithAppKey("<APP_KEY>")
return true
}
macOS
import SwiftyDropbox
func applicationDidFinishLaunching(_ aNotification: Notification) {
DropboxClientsManager.setupWithAppKeyDesktop("<APP_KEY>")
}
Begin the authorization flow
You can commence the auth flow by calling authorizeFromControllerV2:controller:openURL method in your application's
view controller. Note that the controller reference will be weakly held. For SwiftUI applications nil can be passed in for the controller argument and the app's root view controller will be used to present the flow.
From your view controller:
iOS
import SwiftyDropbox
func myButtonInControllerPressed() {
// OAuth 2 code flow with PKCE that grants a short-lived token with scopes, and performs refreshes of the token automatically.
let scopeRequest = ScopeRequest(scopeType: .user, scopes: ["account_info.read"], includeGrantedScopes: false)
DropboxClientsManager.authorizeFromControllerV2(
UIApplication.shared,
controller: self,
loadingStatusDelegate: nil,
openURL: { (url: URL) -> Void in UIApplication.shared.open(url, options: [:], completionHandler: nil) },
scopeRequest: scopeRequest
)
}
macOS
import SwiftyDropbox
func myButtonInControllerPressed() {
// OAuth 2 code flow with PKCE that grants a short-l
