> ## 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.

# Flutter Installation

> Add AppDNA to your Flutter project

<Info>
  **Supported on:** iOS SDK `1.0.61+` · Android SDK `1.0.33+` · Flutter SDK `1.0.3+`
</Info>

## Requirements

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

| Requirement    | Minimum Version |
| -------------- | --------------- |
| Dart           | 3.0+            |
| Flutter        | 3.10+           |
| iOS            | 16.0+           |
| Android minSdk | 24              |

<Warning>
  The Flutter SDK uses platform channels to delegate rendering, storage, and network I/O to the native iOS and Android SDKs under the hood, so every paywall, onboarding flow, and in-app message looks and feels platform-native. Your project must meet the native platform requirements as well.
</Warning>

## Installation

Add the AppDNA SDK to your `pubspec.yaml`:

```yaml theme={null}
dependencies:
  appdna_sdk: ^1.0.9
```

Then install dependencies:

```bash theme={null}
flutter pub get
```

## Firebase Configuration

The AppDNA SDK uses Firebase Firestore for real-time configuration delivery (paywalls, experiments, feature flags, onboarding flows). You must add Firebase configuration files for each platform your app targets.

### Step 1: Download Firebase Config Files

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

### Step 2: Add iOS Configuration

1. Open `ios/Runner.xcworkspace` in Xcode
2. Drag `GoogleService-Info-AppDNA.plist` into the `Runner` folder in the project navigator
3. Ensure **"Copy items if needed"** is checked
4. Select the **Runner** target in the **"Add to targets"** section

### Step 3: Add Android Configuration

Place the `google-services-appdna.json` file in the Android app module directory:

```
your-project/
  android/
    app/
      google-services-appdna.json    <-- place here
```

Ensure the Google Services plugin is applied in your `android/app/build.gradle`:

```groovy theme={null}
apply plugin: 'com.google.gms.google-services'
```

And the classpath is added to `android/build.gradle`:

```groovy theme={null}
buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.4.0'
    }
}
```

### Step 4: Add firebase\_core Dependency

Add `firebase_core` to your `pubspec.yaml`:

```yaml theme={null}
dependencies:
  appdna_sdk: ^1.0.9
  firebase_core: ^2.24.0
```

Then install dependencies:

```bash theme={null}
flutter pub get
```

<Warning>
  Without the Firebase config files, 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 initializes a separate named Firebase instance using `GoogleService-Info-AppDNA.plist` (iOS) and `google-services-appdna.json` (Android). Your existing Firebase setup is not affected. Just add the AppDNA config files alongside your own.
</Note>

## Architecture

The `appdna_sdk` package uses Flutter platform channels for rendering, storage, and network I/O. The Dart layer marshals method calls and streams events from the native side, so every feature reaches your Flutter app at native performance with native UI primitives.

### Platform Channels

The SDK registers the following platform channels:

| Channel                          | Type          | Purpose                                               |
| -------------------------------- | ------------- | ----------------------------------------------------- |
| `com.appdna.sdk/main`            | MethodChannel | Primary SDK operations                                |
| `com.appdna.sdk/billing`         | MethodChannel | Billing and purchase operations                       |
| `com.appdna.sdk/web_entitlement` | EventChannel  | Web entitlement change stream                         |
| `com.appdna.sdk/events/push`     | EventChannel  | Push notification delegate events (received + tapped) |
| `com.appdna.sdk/entitlements`    | EventChannel  | Entitlement changes stream                            |
| `com.appdna.sdk/events/<module>` | EventChannel  | Per-module delegate event streams                     |

<Info>
  You do not need to interact with platform channels directly. The `AppDNA` class and its module accessors provide a high-level Dart API that wraps all channel communication.
</Info>

## Native Dependencies

The Flutter SDK inherits the dependencies of the underlying native SDKs. These are resolved automatically by CocoaPods (iOS) and Gradle (Android):

| Platform | Dependency        | Version          | Purpose                             |
| -------- | ----------------- | ---------------- | ----------------------------------- |
| iOS      | KeychainAccess    | \~> 4.2          | Secure storage for tokens and IDs   |
| iOS      | FirebaseFirestore | >= 11.0, \< 13.0 | Real-time remote configuration sync |
| Android  | Firebase BoM      | latest           | Firestore + analytics + messaging   |
| Android  | Play Billing      | latest           | In-app purchases and subscriptions  |

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

<Note>
  Lottie and Rive animation support is provided by the native SDKs. On iOS, add `lottie-ios` and `rive-ios` to your `Podfile` if you use those formats. On Android, the equivalent dependencies are bundled with the native AppDNA SDK.
</Note>

## Import

Import the SDK in any Dart file where you need to use it:

```dart theme={null}
import 'package:appdna_sdk/appdna_sdk.dart';
```

This single import exposes the `AppDNA` entry point, every module accessor, the canonical delegate interfaces (`AppDNAPushDelegate`, `AppDNAPaywallDelegate`, `AppDNAOnboardingDelegate`, etc.), and all DTOs (`Entitlement`, `ProductInfo`, `PurchaseResult`, `PaywallContext`, ...).

## Verify Installation

After adding the dependency, verify the SDK is correctly installed by printing the version:

```dart theme={null}
import 'package:appdna_sdk/appdna_sdk.dart';

void main() async {
  final version = await AppDNA.getSdkVersion();
  print(version); // native version, e.g. iOS "1.0.71" or Android "1.0.43"
}
```

<Check>
  You should see a version string printed in the debug console. If the import fails, run `flutter pub get` again and restart your IDE.
</Check>

## Troubleshooting

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

```dart theme={null}
// Call a few seconds after configure() to allow bootstrap to complete
Future.delayed(const Duration(seconds: 5), () {
  AppDNA.diagnose();
});
```

This prints a diagnostic report to the platform console (Xcode debug area on iOS, Logcat on Android):

```
╔══════════════════════════════════════════
║  AppDNA SDK Diagnostic Report  v1.0.8
║  (iOS 1.0.71 / Android 1.0.43)
╠══════════════════════════════════════════
║ ✅ 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
║ ✅ Flutter bridge: 8 EventChannels connected
╠══════════════════════════════════════════
║ ✅ 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_`. Copy directly from **Settings → SDK** in the AppDNA Console.                                                                                             |
| ❌ Bootstrap: failed                       | Check API key and internet connection.                                                                                                                                                                   |
| ❌ Firebase: no secondary app              | Add `GoogleService-Info-AppDNA.plist` to your iOS target AND `google-services-appdna.json` to `android/app/`.                                                                                            |
| ⚠️ Firebase: using default app            | Your own Firebase is being used instead of AppDNA's — add the AppDNA-specific config file.                                                                                                               |
| `MissingPluginException` on configure     | Run `flutter clean && flutter pub get`, then rebuild the iOS pods (`cd ios && pod install`) and the Android Gradle project.                                                                              |
| Build fails on iOS with `BGTaskScheduler` | The iOS native SDK registers background event uploads. Ensure your iOS deployment target is 16.0+ and the `Background Modes → Background fetch` capability is enabled if you customize background tasks. |

For more verbose output, set `AppDNAOptions(logLevel: AppDNALogLevel.debug)` during development to surface SDK activity.

## Next Steps

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