> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appdna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Installation

> Add AppDNA to your iOS project

<Info>
  **Supported on:** iOS SDK `1.0.61+`
</Info>

## Requirements

Before integrating the AppDNA iOS SDK, ensure your project meets the following minimum requirements:

| Requirement | Minimum Version |
| ----------- | --------------- |
| iOS         | 16.0+           |
| Swift       | 5.9+            |
| Xcode       | 16+             |

<Warning>
  Projects targeting iOS versions below 16.0 are not supported. The SDK uses Swift concurrency features and modern SwiftUI APIs that require iOS 16.0 as a minimum deployment target.
</Warning>

## Installation

### Swift Package Manager (Recommended)

Add the AppDNA SDK to your project using Swift Package Manager:

1. In Xcode, go to **File > Add Package Dependencies...**
2. Enter the repository URL:

```
https://github.com/appdna-ai-inc/appdna-sdk-ios.git
```

3. Set the dependency rule to **Up to Next Major Version** starting from `1.0.71`.
4. Select the `AppDNASDK` package product and add it to your target.

Alternatively, add it directly to your `Package.swift`:

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/appdna-ai-inc/appdna-sdk-ios.git", from: "1.0.71")
]
```

Then add the product to your target's dependencies:

```swift theme={null}
.target(
    name: "YourApp",
    dependencies: [
        .product(name: "AppDNASDK", package: "appdna-sdk-ios")
    ]
)
```

### CocoaPods

Add the following to your `Podfile`:

```ruby theme={null}
pod 'AppDNASDK', '~> 1.0.71'
```

Then run:

```bash theme={null}
pod install
```

<Note>
  The pod is published from the `AppDNASDK.podspec` in the SDK repository. Make sure your CocoaPods repo is up to date by running `pod repo update` if the pod is not found.
</Note>

## Firebase Configuration

The AppDNA SDK uses Firebase Firestore for real-time configuration delivery (paywalls, experiments, feature flags, onboarding flows). You must add a Firebase configuration file to your project.

### Step 1: Download GoogleService-Info-AppDNA.plist

1. Log into your [AppDNA Console](https://console.appdna.ai)
2. Go to **Settings → SDK**
3. Click **Download Firebase Config** to download `GoogleService-Info-AppDNA.plist`

### Step 2: Add to Your Xcode Project

1. Drag `GoogleService-Info-AppDNA.plist` into your Xcode project navigator
2. Ensure **"Copy items if needed"** is checked
3. Select your app target in the **"Add to targets"** section

### Step 3: Add Background Task Permission

Add the following to your app's `Info.plist` to enable background event uploads:

```xml theme={null}
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>ai.appdna.sdk.eventUpload</string>
</array>
```

```swift theme={null}
// In AppDelegate.swift — must be called before AppDNA.configure()
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    AppDNA.registerBackgroundTasks()
    AppDNA.configure(apiKey: "YOUR_API_KEY")
    return true
}
```

<Warning>
  Without `GoogleService-Info-AppDNA.plist`, the SDK cannot fetch remote configuration (paywalls, experiments, feature flags). Events will still be tracked, but remote features will not work.
</Warning>

<Note>
  If your app already uses Firebase for your own services (Realtime Database, Analytics, Crashlytics), AppDNA automatically creates a separate named Firebase instance using `GoogleService-Info-AppDNA.plist`. Your existing Firebase setup is not affected. Just add the AppDNA plist alongside your own `GoogleService-Info.plist`.
</Note>

## Dependencies

The following dependencies are automatically included with the SDK. You do not need to add them manually:

| Dependency        | Version          | Purpose                             |
| ----------------- | ---------------- | ----------------------------------- |
| KeychainAccess    | \~> 4.2          | Secure storage for tokens and IDs   |
| FirebaseFirestore | >= 11.0, \< 13.0 | Real-time remote configuration sync |

<Info>
  If your project already includes these dependencies, ensure your version constraints are compatible with the versions listed above. SPM and CocoaPods will resolve version conflicts automatically in most cases.
</Info>

<Note>
  Lottie and Rive animation support requires adding `lottie-ios` and `rive-ios` as separate SPM dependencies in your project.
</Note>

## Verify Installation

After adding the SDK, verify it is correctly installed by importing the module and printing the SDK version:

```swift theme={null}
import AppDNASDK

print(AppDNA.sdkVersion) // "1.0.71"
```

If the import succeeds and the version prints correctly, the SDK is ready to configure.

<Check>
  You should see `1.0.71` printed in the Xcode console. If you get a "No such module" error, clean your build folder (Cmd+Shift+K) and rebuild.
</Check>

## Troubleshooting

If you encounter issues during integration, call `AppDNA.diagnose()` after configuration to get a full health report:

```swift theme={null}
// Call a few seconds after configure() to allow bootstrap to complete
DispatchQueue.main.asyncAfter(deadline: .now() + 5) {
    AppDNA.diagnose()
}
```

This prints a diagnostic report to the Xcode console:

```
╔══════════════════════════════════════════
║  AppDNA SDK Diagnostic Report  v1.0.71
╠══════════════════════════════════════════
║ ✅ API Key: sandbox key (adn_test_...50ef)
║ ✅ Environment: sandbox
║ ✅ Bootstrap: orgId=..., appId=...
║ ✅ Firebase: secondary app 'appdna' configured
║ ✅ Identity: anonId=a1b2c3d4...
║ ✅ Event Queue: initialized
║ ✅ Remote Config: initialized
║ ✅ Modules: paywalls, onboarding, messages, surveys, billing, push, experiments
╠══════════════════════════════════════════
║ ✅ SDK is fully operational
╚══════════════════════════════════════════
```

Any items marked with **❌** indicate a configuration issue. Common fixes:

| Issue                          | Fix                                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------------------- |
| ❌ API Key: invalid format      | Key must start with `adn_live_` or `adn_test_`                                              |
| ❌ Bootstrap: failed            | Check API key and internet connection                                                       |
| ❌ Firebase: no secondary app   | Add `GoogleService-Info-AppDNA.plist` to your target                                        |
| ⚠️ Firebase: using default app | Your own Firebase is being used instead of AppDNA's — add `GoogleService-Info-AppDNA.plist` |

## Next Steps

Once the SDK is installed, proceed to the [Quickstart](/sdks/ios/quickstart) guide to configure the SDK and start tracking events.