Skip to main content
Supported on: iOS SDK 1.0.61+ · Android SDK 1.0.33+ · Flutter SDK 1.0.3+

​
Requirements

Before integrating the AppDNA Flutter SDK, ensure your project meets the following minimum requirements:
RequirementMinimum Version
Dart3.0+
Flutter3.10+
iOS15.0+
Android minSdk24
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.

​
Installation

Add the AppDNA SDK to your pubspec.yaml: 
dependencies:
  appdna_sdk: ^1.0.3
Then install dependencies: 
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
  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: 
apply plugin: 'com.google.gms.google-services'
And the classpath is added to android/build.gradle: 
buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.4.0'
    }
}

​
Step 4: Add firebase_core Dependency

Add firebase_core to your pubspec.yaml: 
dependencies:
  appdna_sdk: ^1.0.3
  firebase_core: ^2.24.0
Then install dependencies: 
flutter pub get
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.
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.

​
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:
ChannelTypePurpose
com.appdna.sdk/mainMethodChannelPrimary SDK operations
com.appdna.sdk/billingMethodChannelBilling and purchase operations
com.appdna.sdk/web_entitlementEventChannelWeb entitlement change stream
com.appdna.sdk/push_receivedEventChannelPush notification received stream
com.appdna.sdk/push_tappedEventChannelPush notification tapped stream
com.appdna.sdk/entitlementsEventChannelEntitlement changes stream
com.appdna.sdk/events/<module>EventChannelPer-module delegate event streams
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.

​
Native Dependencies

The Flutter SDK inherits the dependencies of the underlying native SDKs. These are resolved automatically by CocoaPods (iOS) and Gradle (Android):
PlatformDependencyVersionPurpose
iOSKeychainAccess~4.2.2Secure storage for tokens and IDs
iOSFirebaseFirestore~11.0Real-time remote configuration sync
AndroidFirebase BoMlatestFirestore + analytics + messaging
AndroidPlay BillinglatestIn-app purchases and subscriptions
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.
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.

​
Import

Import the SDK in any Dart file where you need to use it: 
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: 
import 'package:appdna_sdk/appdna_sdk.dart';

void main() async {
  final version = await AppDNA.getSdkVersion();
  print(version); // native version, e.g. iOS "1.0.61" or Android "1.0.33"
}
You should see a version string printed in the debug console. If the import fails, run flutter pub get again and restart your IDE.

​
Troubleshooting

If you encounter issues during integration, call AppDNA.diagnose() after configuration to get a full health report: 
// 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.3
║  (iOS 1.0.61 / Android 1.0.33)
╠══════════════════════════════════════════
║ ✅ 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:
IssueFix
❌ API Key: invalid formatKey must start with adn_live_ or adn_test_. Copy directly from Settings → SDK in the AppDNA Console.
❌ Bootstrap: failedCheck API key and internet connection.
❌ Firebase: no secondary appAdd GoogleService-Info-AppDNA.plist to your iOS target AND google-services-appdna.json to android/app/.
⚠️ Firebase: using default appYour own Firebase is being used instead of AppDNA’s — add the AppDNA-specific config file.
MissingPluginException on configureRun flutter clean && flutter pub get, then rebuild the iOS pods (cd ios && pod install) and the Android Gradle project.
Build fails on iOS with BGTaskSchedulerThe iOS native SDK registers background event uploads. Ensure your iOS deployment target is 15.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 guide to configure the SDK and start tracking events.