Public Preview - This version is in public preview and subject to changes. For production use, please use SDK v4.
To install the Ditto SDK and start syncing offline:
1

Confirm that you meet the minimum requirements. (Prerequisites)
2

Install the necessary dependencies. (Installing Package Dependencies)
3

Set up your app permissions. (Configuring Permissions)
4

Authenticate with Ditto Server and then start syncing offline. (Integrating and Initializing Sync)

​
Prerequisites

Following are the minimum requirements that must be met before attempting to install Ditto:
  • iOS version 14 or later
  • Mac Catalyst 14 or later
  • macOS (AppKit) version 11 or later
  • tvOS version 14 or later

​
Installing Package Dependencies

Using Xcode or CocoaPods, add the necessary dependencies:
1

Click File, and then select Add Package Dependencies… from the menu.
2

Copy-paste the following URL into the search box in the upper-right corner: https://github.com/getditto/DittoSwiftPackage
3

Select dittoswiftpackage from the list.
4

Click the Dependency Rule dropdown menu and select Up to Next Major Version from the list.
5

In the field on the right, set the version to the latest DittoSwift version in the Release Notes.
6

For more information, see the official Apple documentation.

​
Configuring Permissions

Once you’ve added Ditto SDK package dependencies:
1

Configure your project’s Info.plist file to ensure the necessary permissions for Bluetooth Low Energy (LE) and local network services are included. (Ensuring Privacy Compliance)
2

If enabling the Data Protection entitlement, allow access after your end users have unlocked their device for the first time after a system restart. (Setting Protection Entitlement)

​
Ensuring Privacy Compliance

Configure your app for compliance with Apple’s guidelines for iOS permissions by doing the following. For more information, see the official Apple documentation for Privacy.
1

From Xcode, add a new Custom iOS Target Properties entry:
  1. From the left navigator area, click your project.
  2. In the editor that appears, click Info tab.
  3. Right-click any row in the list, and then select Add Row from the menu.
For instructions on configuring permissions for your app, see Cloud Authentication.
2

From your project’s Info.plistfile, add the following key-value pairs, which display as dismissable prompts to your end users explaining why the app requires certain permissions.
Key: NSBluetoothAlwaysUsageDescription
Type: String
Value: Uses Bluetooth to connect and sync with nearby devices
Key: NSBluetoothPeripheralUsageDescription
Type: String
Value: Uses Bluetooth to connect and sync with nearby devices
Key: NSLocalNetworkUsageDescription
Type: String
Value: Uses WiFi to connect and sync with nearby devices
Key: NSBonjourServices
Type: Array
Value: Item0: "_http-alt._tcp." (String)
3

If your end users prefer a language other than English, replace each default string assigned to Value with their language equivalents.
4

From Xcode, ensure your app continues to sync while it runs in the background, as well as when the end-user device is locked by enabling Bluetooth Background Modes:
  1. From the left navigator area, click your project.
  2. Click Signing & Capabilities.
  3. Click + Capability and then, from the modal that appears, search and select Background Modes.
  4. From TARGETS, select your app from the list.
  5. From Background Modes, click to select the following:
  • Uses Bluetooth LE accessories
  • Acts as a Bluetooth LE accessory

​
Setting Protection Entitlement

If enabling the Data Protection entitlement, allow access after the end user has unlocked their device for the first time after a system restart by setting the entitlement to NSFileProtectionCompleteUntilFirstUserAuthentication. For more information, see the official Apple documentation for Data Protection Entitlement.

​
Integrating and Initializing Sync

Once you’ve set up your environment, import the Ditto SDK in your codebase and obtain your access credentials.
Unless you have a specialized use case, such as a government app, you must connect to the internet at least once before you can sync offline with other peers.
1

From the top-most scope of your app’s codebase, add the following to set up authentication and start syncing offline.
2

Replace the database ID and development token with your access credentials available from the portal.
For instructions on how to obtain your access credentials, see Getting SDK Connection Details
Swift
// Your HTTP Cloud URL Endpoint
let config = DittoConfig(
    databaseID: "REPLACE_ME_WITH_YOUR_DATABASE_ID", // This was "appID" in v4
    connect: .server(url: URL(string: "REPLACE_ME_WITH_YOUR_URL")), // This was "Custom Auth URL" in v4
)

let ditto = try await Ditto.open(config: config)

// Set up authentication expiration handler (required for server connections)
ditto.auth?.expirationHandler = { [weak self] ditto, secondsRemaining in

    // Authenticate when token is expiring

    ditto.auth?.login(
        // Your development token, replace with your actual token
        token: "REPLACE_ME_WITH_YOUR_DEVELOPMENT_TOKEN", 
        // Use .development or your actual provider name
        provider: .development 
    ) { clientInfo, error in
        if let error = error {
            print("Authentication failed: \(error)")
        } else {
            print("Authentication successful")
        }
    }
}

try ditto.sync.start()

​
Migrating from v4

If you’re upgrading from Ditto SDK v4 to v5, note that DittoObjC SDK has been removed. When updating your package dependency:
  1. Remove the existing Ditto package dependency:
    • Go to Project → Package Dependencies
    • Select the Ditto package and click the minus button to remove it
  2. Re-add the Ditto package following the installation steps above
  3. Ensure DittoObjC is not linked or embedded in your target:
    • Check your target’s Frameworks, Libraries, and Embedded Content section
    • Remove any references to DittoObjC if present
If you encounter a “Missing package product DittoObjC” error, follow the steps above to remove and re-add the package dependency.

​
Using crash reporters in iOS apps

1

Setup

Integrate the crash reporter SDK into your app, following their documentation.
2

Check crash collection

Trigger a panic and check that it was registered in your crash reporter. You can use the DittoExperimental.triggerTestPanic() function to do so. At this point, without native symbols, the crash will be unreadable. If you are not seeing any crashes in the reporter, check that you have integrated its components correctly.
3

Upload symbols

For release builds, you can obtain the dsym files from Xcode. They are included in the .xcarchive file. Navigate to Xcode → Window → Organizer → Archives → (Right click on a specific build) → Show in Finder → Show Package Contents → dSYMs Folder. Here you can find all the required files:
  1. Your own app’s symbol file, such as MyApp.app.dSYM
  2. The Ditto DittoSwift.framework.dSYM files.
    Check your crash reporter’s documentation for how to do this. For example Sentry provides a CLI tool.
4

Final test

Trigger a new panic and notice that the crash is now symbolicated by the reporting framework.