Skip to main content
Supported on: iOS SDK 1.0.61+ · Android SDK 1.0.33+ · React Native SDK 1.0.4+

​
Requirements

Before integrating the AppDNA React Native SDK, ensure your project meets the following minimum requirements:
RequirementMinimum Version
React Native0.70+
Node18+
iOS15.0+
Android minSdk24
The React Native SDK uses the native module bridge 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

Install the AppDNA SDK package: 
yarn add @appdna/react-native-sdk
Or with npm: 
npm install @appdna/react-native-sdk
Then install the iOS Pods: 
cd ios && pod install && cd ..
React Native autolinking (0.60+) wires the native iOS and Android modules automatically — no manual react-native link step is required.

​
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/<YourApp>.xcworkspace in Xcode
  2. Drag GoogleService-Info-AppDNA.plist into your app target’s folder in the project navigator
  3. Ensure “Copy items if needed” is checked
  4. Select your app 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'
    }
}
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/react-native-sdk package uses React Native’s native module bridge for rendering, storage, and network I/O. The TypeScript layer marshals method calls and emits events from the native side through NativeEventEmitter, so every feature reaches your React Native app at native performance with native UI primitives.

​
Native Modules and Events

The SDK registers the following native modules and event names:
SurfaceTypePurpose
NativeModules.AppDNANativeModulePrimary SDK operations
AppDNA_billingBridged methodsBilling and purchase operations
AppDNA_web_entitlement_changedEmitter eventWeb entitlement change events
AppDNA_push_receivedEmitter eventPush notification received events
AppDNA_push_tappedEmitter eventPush notification tapped events
AppDNA_entitlements_changedEmitter eventEntitlement change events
AppDNA_<module>_eventEmitter eventPer-module delegate event streams
You do not need to interact with the native module bridge directly. The AppDNA class and its module accessors provide a high-level TypeScript API that wraps all bridge communication.

​
Native Dependencies

The React Native 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 TypeScript / JavaScript file where you need to use it: 
import { AppDNA } from '@appdna/react-native-sdk';
This entry point exposes the AppDNA static class, 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 { AppDNA } from '@appdna/react-native-sdk';

async function bootstrap(): Promise<void> {
  const version = await AppDNA.getSdkVersion();
  console.log(version); // native version, e.g. iOS "1.0.61" or Android "1.0.33"
}
You should see a version string printed in the Metro / Flipper / Xcode debug area. If the import fails, run yarn install again and rebuild the native projects.

​
Troubleshooting

If you encounter issues during integration, call AppDNA.diagnose() after configuration to get a full health report: 
import { AppDNA } from '@appdna/react-native-sdk';

// Call a few seconds after configure() to allow bootstrap to complete
setTimeout(() => {
  AppDNA.diagnose();
}, 5000);
This prints a diagnostic report to the platform console (Xcode debug area on iOS, Logcat on Android): 
╔══════════════════════════════════════════
║  AppDNA SDK Diagnostic Report  v1.0.4
║  (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
║ ✅ React Native bridge: 8 native events wired
╠══════════════════════════════════════════
║ ✅ 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.
Invariant Violation: Native module AppDNA is nullRe-run cd ios && pod install, then rebuild the iOS app from Xcode. On Android, run cd android && ./gradlew clean and rebuild.
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 logLevel: 'debug' in AppDNAOptions 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.