--- title: Swift slug: v4-8/install-guides/swift icon: {"faIcon":"fa-brands fa-swift"} docTags: createdAt: 2023-07-28T20:16:57.748Z --- You can integrate the Ditto SDK into Swift projects to develop native apps for Apple iOS and macOS platforms. To install the Ditto SDK and start syncing offline: ::::WorkflowBlock :::WorkflowBlockItem Confirm that you meet the minimum requirements. ([Prerequisites](./#prerequisites)) ::: :::WorkflowBlockItem Install the necessary dependencies. ([Installing Package Dependencies](./#installing-package-dependencies)) ::: :::WorkflowBlockItem Set up your app permissions. ([Configuring Permissions](./#configuring-permissions)) ::: :::WorkflowBlockItem Authenticate with the Big Peer and then start syncing offline. ([Integrating and Initializing Sync](./#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: :::::::Tabs ::::::Tab{title="Xcode"} :::::WorkflowBlock :::WorkflowBlockItem Click **File**, and then select **Add Package Dependencies...** from the menu. ::: ::::WorkflowBlockItem 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](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: - If building a production-level app, see [Developing for Production](docId\:gLpoucfs6QkwdtpfNZeDs). - If testing Ditto with Apple Vision Pro devices, see [Exploring with visionOS beta](docId\:gLpoucfs6QkwdtpfNZeDs). 4. Click **Add Package**. ![](https://api.archbee.com/api/optimize/qoRkNxW5fJ81r_NqVpc8C/8nURqBPkpxUJ_3zsaETi7_image.png) :::hint{type="info"} For more information, see the official Apple documentation > [Adding package dependencies to your app](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app#3512138). ::: :::: :::WorkflowBlockItem From the **Choose Package Products for DittoSwiftPackage** modal: 1. Click **Add to Target** and select your app from the list. 2. Click **Add Package**. ![](https://api.archbee.com/api/optimize/qoRkNxW5fJ81r_NqVpc8C/_MhO4O0NX4udzMrvZJDRz_image.png) ::: ::::: ## Developing for Production To install the latest production release of the Ditto SDK for Swift: ::::WorkflowBlock :::WorkflowBlockItem Click the **Dependency Rule** dropdown menu and select **Up to Next Major Version** from the list. ::: :::WorkflowBlockItem In the field on the right, set the version to **4.7.2**. ![](https://api.archbee.com/api/optimize/qoRkNxW5fJ81r_NqVpc8C/TucasfydjtSz2v6lDGPai_image.png) ::: :::: ## Exploring with visionOS beta Ditto now supports the visionOS platform in beta for our Swift SDK. :::hint{type="info"} For an overview of the Ditto SDK for visionOS, including steps outlining example integration with our demo chat app, [DittoChat](https://apps.apple.com/us/app/dittochat/id1450111256), see [visionOS on Swift](docId:9eYfPNj_xG4j-R85evDAh). ::: To install the visionOS beta Ditto Swift package, set the **Dependency Rule** to **4.8.0-v** as follows: ::::WorkflowBlock :::WorkflowBlockItem Click the **Dependency Rule** dropdown menu and select **Exact Version** from the list. ::: :::WorkflowBlockItem In the field on the right, set the version to **4.7.2**. ![](https://api.archbee.com/api/optimize/qoRkNxW5fJ81r_NqVpc8C/1OnMN5hYXMSGYnIdTg94A_image.png) ::: :::: :::hint{type="info"} For the visionOS binaries in GitHub, see [4.8.0-visionos-beta.1](https://github.com/getditto/DittoSwiftPackage/releases/tag/4.8.0-visionos-beta.1) library in the [DittoSwiftPackage](https://github.com/getditto/DittoSwiftPackage) repo. ::: :::::: ::::::Tab{title="CocoaPods"} :::::WorkflowBlock :::WorkflowBlockItem Confirm that you have CocoaPods version 1.1.0 or later installed. For installation and upgrade instructions, see the official CocoaPods [Getting Started](https://guides.cocoapods.org/using/getting-started.html#installation) Guide. ::: :::WorkflowBlockItem Open the Podfile for your project, and then add the following to indicate to use dynamic frameworks for the pods you're integrating: `use_frameworks!` ::: ::::WorkflowBlockItem From your project directory, install the `DittoSwift` framework: :::CodeblockTabs bash ```none pod 'DittoSwift' ``` ::: :::: ::::WorkflowBlockItem Install the latest version of Ditto SDK package dependencies: :::CodeblockTabs ```none pod install --repo-update ``` ::: :::: ::::: :::::: ::::::: # Configuring Permissions Once you've added Ditto SDK package dependencies: ::::WorkflowBlock :::WorkflowBlockItem 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](./#ensuring-privacy-compliance)) ::: :::WorkflowBlockItem 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](./#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](https://developer.apple.com/design/human-interface-guidelines/privacy). :::::::WorkflowBlock ::::WorkflowBlockItem 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. :::hint{type="info"} For instructions on configuring permissions for your app, see [Cloud Authentication](docId\:D0B4xrfN45yeM15qCYcOb). ::: ::Image[]{src="https://api.archbee.com/api/optimize/qoRkNxW5fJ81r_NqVpc8C/Ndgl7gVXr1LJ0-s8tApoL_image.png" size="96" width="2102" height="886" position="flex-start" showCaption="false"} :::: ::::::WorkflowBlockItem From your project's `Info.plist`file, add the following key-value pairs, which display as dismissable prompts to your end users explaining why the app requires certain permissions. :::::Tabs ::::Tab{title="From Info Tab"} :::CodeblockTabs ```none 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) ``` ::: :::: :::Tab{title="From Source Code"} ```xml NSBluetoothAlwaysUsageDescription Uses Bluetooth to connect and sync with nearby devices NSBluetoothPeripheralUsageDescription Uses Bluetooth to connect and sync with nearby devices NSLocalNetworkUsageDescription Uses WiFi to connect and sync with nearby devices NSBonjourServices _http-alt._tcp. ``` ::: ::::: :::::: :::WorkflowBlockItem If your end users prefer a language other than English, replace each default string assigned to `Value` with their language equivalents. ::: :::WorkflowBlockItem 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** ![](https://api.archbee.com/api/optimize/qoRkNxW5fJ81r_NqVpc8C/wkc2x271jClXJRrXrKrNY_image.png) ::: ::::::: ## 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](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_default-data-protection). # Integrating and Initializing Sync Once you've set up your environment, import the Ditto SDK in your codebase and obtain your access credentials. :::hint{type="warning"} 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. For more information, contact Ditto. (See [Contact Us](docId\:n4CiVTbQAL1SmgjNO8aM8)) ::: :::::WorkflowBlock :::WorkflowBlockItem From the top-most scope of your app's codebase, add the following to set up authentication and start syncing offline. ::: ::::WorkflowBlockItem Replace `YOUR_APP_ID` and `YOUR_PLAYGROUND_TOKEN` with your access credentials available from the portal. :::hint{type="info"} For instructions on how to obtain your access credentials, see [Getting Playground Token Credentials](docId\:U214QhYYMCxbV9jnamRFH) ::: ```swift let ditto = Ditto(identity: .onlinePlayground( appID: "YOUR_APP_ID", token: "YOUR_PLAYGROUND_TOKEN" )) do { try ditto.startSync() } catch (let err) { print(err.localizedDescription) } ``` :::: :::::