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
  • (optional) visionOS version 1, 1.1, or 1.2

​
Installing Package Dependencies

Using Xcode or CocoaPods, add the necessary dependencies:
1

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

In the modal that appears:
  1. Copy-paste the following URL into the search box in the upper-right corner: https://github.com/getditto/DittoSwiftPackage
  2. Select dittoswiftpackage from the list.
  3. Click Dependency Rule and select the version of Ditto you want to use:
  1. Click Add Package.
For more information, see the official Apple documentation > Adding package dependencies to your app.
3

From the Choose Package Products for DittoSwiftPackage modal:
  1. Click Add to Target and select your app from the list.
  2. Click Add Package.

​
Developing for Production

To install the latest production release of the Ditto SDK for Swift:
1

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

In the field on the right, set the version to the latest DittoSwift version: (Please check the latest version in Release Notes)

​
Exploring with visionOS beta

Ditto now supports the visionOS platform in beta for our Swift SDK.
For an overview of the Ditto SDK for visionOS, including steps outlining example integration with our demo chat app, DittoChat, see visionOS on Swift.
To install the visionOS beta Ditto Swift package, set the Dependency Rule to 4.8.0-v as follows:
1

Click the Dependency Rule dropdown menu and select Exact Version from the list.
2

In the field on the right, set the version to the latest DittoSwift version: (Please check the latest version in Release Notes)
For the visionOS binaries in GitHub, see 4.8.0-visionos-beta.1 library in the DittoSwiftPackage repo.

​
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 YOUR_APP_ID and YOUR_PLAYGROUND_TOKEN with your access credentials available from the portal.
For instructions on how to obtain your access credentials, see Getting SDK Connection Details
Swift
ditto = Ditto(
  identity: DittoIdentity.onlinePlayground(
    appID: "REPLACE_ME_WITH_YOUR_APP_ID",
    token: "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN",
    enableDittoCloudSync: false, // This is required to be set to false to use the correct URLs
    customAuthURL: URL(string: "REPLACE_ME_WITH_YOUR_AUTH_URL")
  )
)

ditto.updateTransportConfig { transportConfig in
  // Set the Ditto Websocket URL
  transportConfig.connect.webSocketURLs.insert("wss://REPLACE_ME_WITH_YOUR_WEBSOCKET_URL")
}

// Disable DQL strict mode so that collection definitions are not required in DQL queries
try await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = false")

do {
  try ditto.startSync()
} catch {
  print(error.localizedDescription)
}

​
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 DittoObjC.framework.dSYM and 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.