Flutter Installation

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:

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

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

Then install dependencies:

flutter pub get

Firebase Configuration

The AppDNA SDK uses Firebase Firestore for 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

Log into your AppDNA Console
Go to Settings → SDK
Click Download Firebase Config to download both:
- GoogleService-Info-AppDNA.plist (for iOS)
- google-services-appdna.json (for Android)

Step 2: Add iOS Configuration

Open ios/Runner.xcworkspace in Xcode
Drag GoogleService-Info-AppDNA.plist into the Runner folder in the project navigator
Ensure “Copy items if needed” is checked
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.21
  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:

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

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):

Platform	Dependency	Version	Purpose
iOS	KeychainAccess	~> 4.2	Secure storage for tokens and IDs
iOS	FirebaseFirestore	>= 11.0, < 13.0	Remote configuration fetch
Android	Firebase BoM	latest	Firestore + analytics + messaging
Android	Play Billing	latest	In-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, …).

Interactive maps

An onboarding step can contain a map. The static map needs no setup — the provider key is delivered with your configuration.

Enable the Maps SDK for this platform in Google Cloud, alongside the Maps Static API the map image already uses: APIs & Services → Library → Maps SDK for iOS and Maps SDK for Android. Pan & zoom is drawn by that SDK, so without it enabled the key is rejected at map start and the step falls back to the still image — every bit of wiring below can be correct and the map still will not move. See Maps for the full key setup.

A pannable map needs one line in your Android host, and nothing at all on iOS. The Maps SDK for Android reads its key from the merged manifest at build time, so add this to android/app/src/main/AndroidManifest.xml:

<application>
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="YOUR_ANDROID_MAPS_API_KEY" />
</application>

Without it the SDK falls back to the static map rather than rendering a grey rectangle, so nothing breaks — the map simply does not pan. The key is always yours; AppDNA never substitutes one of its own, because Google bills the account that owns it.

Your Podfile needs use_frameworks! — the iOS SDK cannot be built from pods built as static libraries (iOS installation), and Flutter’s generated Podfile has it. With dynamic frameworks (plain use_frameworks!, not :linkage => :static), add this to it. Google ships the Maps SDK as a static xcframework, and CocoaPods refuses a static binary inside a dynamically-linked target:

[!] The 'Pods-YourApp' target has transitive dependencies that include statically linked
    binaries: (.../Pods/GoogleMaps/Maps/Frameworks/GoogleMaps.xcframework)

pre_install do |installer|
  Pod::Installer::Xcode::TargetValidator.send(
    :define_method, :verify_no_static_framework_transitive_dependencies
  ) {}
end

That validation guards against the same static code being embedded in several dynamic frameworks. With one consumer — your app — that cannot happen, which is why this is the standard remedy across the GoogleMaps ecosystem.And name the pod in your app target too, inside the target '<YourApp>' do block:

pod 'GoogleMaps', '~> 9.4'

The two lines do different jobs and you need both. The pre_install block lets pod install finish; it does not make CocoaPods link a static framework that reached your app transitively. Without this second line the app compiles and then fails at the linker with Undefined symbols ... _OBJC_CLASS_$_GMSCameraPosition. react-native-maps asks for the same line, for the same reason.

None of this applies to Swift Package Manager. An iOS app that adds AppDNASDK through SPM gets the map engine linked automatically, with no Podfile and nothing to add.

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.83" or Android "1.0.55"
}

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.21
║  (iOS 1.0.83 / Android 1.0.55)
╠══════════════════════════════════════════
║ ✅ 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 guide to configure the SDK and start tracking events.

​Requirements

​Installation

​Firebase Configuration

​Step 1: Download Firebase Config Files

​Step 2: Add iOS Configuration

​Step 3: Add Android Configuration

​Step 4: Add firebase_core Dependency

​Architecture

​Platform Channels

​Native Dependencies

​Import

​Interactive maps

​Verify Installation

​Troubleshooting

​Next Steps

Requirements

Installation

Firebase Configuration

Step 1: Download Firebase Config Files

Step 2: Add iOS Configuration

Step 3: Add Android Configuration

Step 4: Add firebase_core Dependency

Architecture

Platform Channels

Native Dependencies

Import

Interactive maps

Verify Installation

Troubleshooting

Next Steps