SwiftyDropbox

Dropbox API v2 uses two specific data models that require careful handling in Swift:

Union Types

Union types represent a single value that can take on multiple different types depending on its state (the "tag"). To handle them, use a switch statement on the error or result to check the tag state. Once the tag is identified, you can access its associated value. Example: Files.DeleteError can be .pathLookup or .pathWrite.

Datatypes with Subtypes

These are hybrid objects (structs with a tag) that represent a common supertype containing shared fields, but can exist as different specific subtypes at runtime. To access subtype-specific fields, cast the object using a switch statement. Example: Metadata can be cast to Files.FileMetadata, Files.FolderMetadata, or Files.DeletedMetadata.

Error Handling Strategy

When an error occurs, cast it to CallError. You can then switch between .routeError (for API-specific errors like Files.DeleteError) and generic errors like .internalServerError, .authError, or .rateLimitError.

// Handling a Union Type Error
client.files.deleteV2(path: "/path").response { response, error in
    if let error = error {
        switch error as CallError {
        case .routeError(let boxed, _, _, _):
            switch boxed.unboxed as Files.DeleteError {
            case .pathLookup(let lookupError):
                // handle lookup error
            case .pathWrite(let writeError):
                // handle write error
            default: break
            }
        default: break
        }
    }
}

// Handling a Datatype with Subtypes
if let response = response {
    switch response {
    case let fileMetadata as Files.FileMetadata:
        print(fileMetadata)
    case let folderMetadata as Files.FolderMetadata:
        print(folderMetadata)
    default: break
    }
}

Dropbox API v2 requests fall into three categories: RPC, Upload, and Download. All endpoints require a response handler.

Response Handler Arguments

Response handler blocks receive:

1. route result type: The data returned by the endpoint (or Void if the route has no return type).
2. network error: Either a route-specific error or a generic network error.
3. output content: A URL or Data reference (only for Download-style endpoints).

Swift Concurrency (async/await)

As of version 10.0.0, you can use the .response() function with async/await instead of completion handlers.

Request Types

• RPC-style: Standard calls like createFolder.
• Upload-style: Calls like upload that accept Data and support .progress handlers and .cancel().
• Download-style: Calls like download that can download to a local URL or directly into Data.

// Swift Concurrency example
let response = try await client.files.createFolder(path: "/test/path/in/Dropbox/account").response()

// Upload-style with progress and cancellation
let request = client.files.upload(path: "/path", input: fileData)
    .response { response, error in /* handle */ }
    .progress { progressData in /* handle */ }

if someCondition { request.cancel() }

If you intend to contribute to or modify the SDK, follow these steps to set up your local development environment:

1. Clone the repository.
2. Initialize and update submodules:

   git submodule init
   git submodule update

3. Navigate to the platform directory: TestSwifty_[iOS|macOS].
4. Ensure your CocoaPods version matches the version locked in TestSwifty_[iOS|macOS]/Podfile.lock.
5. Run pod install.
6. Open the .xcworkspace in Xcode.

Running Integration Tests: To verify changes using the integration test app:

1. Create a 'Full Dropbox' app on the Dropbox Developer Console and note the App key.
2. In the test app's Info.plist, configure the URL Scheme: URL types > Item 0 (Editor) > URL Schemes > Item 0 to db-[YOUR_APP_KEY].
3. In AppDelegate.swift, replace FULL_DROPBOX_APP_KEY with your actual App key.
4. Run the test app on a device and follow the on-screen instructions.

To support the Dropbox Swift SDK, you must modify your application's .plist file to allow URL scheme queries and to register a custom redirect URL scheme for OAuth 2.0 completion.

1. Allow URL Queries: Add LSApplicationQueriesSchemes to allow the SDK to check if the official Dropbox iOS app is installed. This enables 'Direct auth' on iOS.
2. Register Redirect Scheme: Add a CFBundleURLTypes entry with a scheme formatted as db-<APP_KEY>, where <APP_KEY> is your Dropbox app key from the App Console.

<!-- LSApplicationQueriesSchemes configuration -->
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>dbapi-8-emm</string>
    <string>dbapi-2</string>
</array>

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

Versions 10.0+ support iOS background networking. This allows transfers to continue even if the app is suspended.

Initialization

When calling setupWithAppKey, provide a backgroundSessionIdentifier. For app extensions, also provide a sharedContainerIdentifier and ensure App Groups/Keychain sharing are configured in Xcode.

Reconnecting Requests

Because background requests can span app sessions, you must handle reconnection in your AppDelegate using DropboxClientsManager.handleEventsForBackgroundURLSession.

In the requestsToReconnect block, you receive a collection of results. You must iterate through these and re-attach your completion handlers. To help reconstruct context (like which UI element to update), use .persistingString(string:) on your requests to store metadata that persists across sessions.

// Initialization
DropboxClientsManager.setupWithAppKey(
    "<APP_KEY>",
    backgroundSessionIdentifier: "<BACKGROUND_SESSION_IDENTIFIER>",
    requestsToReconnect: { requestResults in
       // Handle reconnection logic
   }
)

// Reconnecting in AppDelegate
func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {
    DropboxClientsManager.handleEventsForBackgroundURLSession(
        with: identifier,
        creationInfos: [],
        completionHandler: completionHandler,
        requestsToReconnect: { requestResults in
            processReconnect(requestResults: requestResults)
        }
    )
}