React Native Quickstart

Supported on: iOS SDK 1.0.70+ · Android SDK 1.0.42+ · React Native SDK 1.0.7+ (New Architecture only)

This guide walks you through configuring the AppDNA SDK, identifying users, and tracking your first event in a React Native application.

1. Configure the SDK

Initialize AppDNA as early as possible in your app lifecycle, typically in your app entry point (index.js, App.tsx, or similar) before rendering the root component:

import { AppDNA } from '@appdna-ai/react-native-sdk';

async function bootstrap(): Promise<void> {
  await AppDNA.configure('adn_live_xxx', 'production', { logLevel: 'debug' });
}

void bootstrap();

If you don’t have your own Firebase: The AppDNA SDK manages a separate named Firebase instance internally — no firebase package install required.If you already use Firebase in your app (via @react-native-firebase/app or similar): the SDK automatically initializes its own named Firebase instance from GoogleService-Info-AppDNA.plist (iOS) and google-services-appdna.json (Android). Your existing Firebase setup is not affected.

Call AppDNA.configure(...) exactly once before using any other SDK methods. Calling it multiple times will result in undefined behavior.

Configuration Options

The AppDNAOptions interface lets you customize SDK behavior:

Parameter	Type	Default	Description
`flushInterval`	`number?`	`30`	Seconds between automatic event flushes. When not set, the server’s value from the bootstrap request applies once the bootstrap succeeds, if it is positive
`batchSize`	`number?`	not set	A cap on the batch size the network sets (100 on Wi-Fi or wired; on cellular, 20 when the system marks the connection expensive (iOS: every cellular connection) or metered (Android: most plans), otherwise 50): the queue is flushed when it reaches the smaller of the two, and each upload sends at most that many. When not set, the value the server returns with the SDK’s bootstrap request is the cap if it is positive (100 today, so nothing is capped). A value below 1 is ignored (the SDK logs a warning), as if not set. Passing the default (100) is the same as not setting it. If your app already passed `batchSize` to an earlier SDK version — where it had no effect — it is now a hard cap: each upload sends at most that many events. Remove it, or raise it, unless that is what you want.
`configTTL`	`number?`	`3600`	Seconds before cached config is considered stale. When not set, the server’s value from the bootstrap request applies once the bootstrap succeeds, if it is positive
`logLevel`	`AppDNALogLevel?`	`'warning'`	Verbosity of SDK console logs
`billingProvider`	`AppDNABillingProvider?`	`'storeKit2'`	Billing integration to use (read by both iOS and Android)
`vetoTimeout`	`number?`	`5`	Seconds a veto hook may take before native applies its default. Sign-in actions in `onBeforeStepAdvance` wait at least 120 s; a `refresh` gets 8 s (a larger `vetoTimeout` does not extend it); `onBeforeStepRender` replies are used only within 3 s
`requireConsent`	`boolean?`	`false`	When `true`, no event at all is emitted until `setConsent(true)`
`notificationIcon`	`number?`	—	Android-only notification small-icon drawable resource id

Environment

The AppDNAEnvironment type controls which backend environment the SDK targets:

Value	Description
`'production'`	Production API and configuration
`'sandbox'`	Test builds — pair it with an `adn_test_` API key

There is no 'staging'. Which data you touch is decided by the API-key prefix (adn_test_ vs adn_live_); this value only tags the SDK’s own environment.

Log Level

The AppDNALogLevel type controls console log verbosity:

Value	Description
`'none'`	No logging
`'error'`	Errors only
`'warning'`	Errors and warnings
`'info'`	Errors, warnings, and info
`'debug'`	All messages including debug

Use 'debug' during development to see all SDK activity. Switch to 'warning' or 'none' for production builds.

Billing Provider

The AppDNABillingProvider type specifies which billing system to use:

Value	Description
`'storeKit2'`	Native StoreKit 2 on iOS, Play Billing on Android (default)
`'revenueCat'`	RevenueCat is your purchase SDK — AppDNA never buys, finishes or acknowledges
`{ type: 'adapty', apiKey }`	Adapty is your purchase SDK — same rule as RevenueCat
`'none'`	Disable the billing module

The provider applies on both platforms. On Android 'storeKit2' means Google Play Billing. Choose 'revenueCat' when RevenueCat is your purchase SDK: AppDNA then never finishes or acknowledges a transaction, an AppDNA paywall tap calls onPaywallPurchaseFailed with errorType: 'providerNotAvailable' (start the RevenueCat purchase from there), and purchases reach AppDNA through the RevenueCat webhook. See Billing.

2. Wait for Ready State

Use onReady to know when the SDK is ready — the bootstrap has succeeded or failed:

await AppDNA.onReady();
console.log('SDK ready');

onReady() takes no callback — it returns a Promise that resolves once the SDK is ready (immediately, if it already is). onReady does not wait for the remote configuration. When it fires, the SDK serves the cached and bundled config, and the remote fetch may still be running (after a failed bootstrap it starts when a retry succeeds). Use remoteConfig.onChanged to pick up the fetched values.

3. Identify Users

Once a user signs in, call identify to associate events with their user ID:

await AppDNA.identify('user-123', {
  plan: 'premium',
  signup_date: '2025-01-15',
});

Traits are merged with any previously set traits. You do not need to pass all traits on every call — only the ones that have changed.

4. Track Events

Track user actions with track:

AppDNA.track('workout_completed', {
  duration: 45,
  type: 'strength',
});

track() is fire-and-forget: it returns void, not a Promise, so there is nothing to await. Native enqueues the event and batches the upload; call flush() when you need delivery. Events are batched and flushed automatically: every flushInterval seconds, when the app goes to the background or returns to the foreground, and when the queue reaches a batch size set by the network (100 events on Wi-Fi or a wired connection, metered or not; 20 on a cellular connection the system marks as expensive (iOS) or metered (Android), which is every cellular connection on iOS and most cellular plans on Android; 50 on any other cellular connection). The batchSize option caps it: with a cap, the queue is flushed at the smaller of the two, and no upload sends more.

5. Flush Events Manually

Force an immediate flush of all queued events:

await AppDNA.flush();

This is useful before the app enters the background or when you need to ensure events are sent immediately. Control whether the SDK collects and sends analytics data:

await AppDNA.setConsent(true);

// And to read the current decision back:
const granted = await AppDNA.isConsentGranted();

setConsent takes a boolean — there is one analytics consent decision, not one per category. When consent is false, events are silently dropped and not queued. No data is sent to AppDNA servers until consent is granted. The decision is persisted — setConsent(false) survives a cold start.

Analytics are opt-OUT by default, and the default emits an event before the user has decided.requireConsent defaults to false. At that default, configure() emits sdk_initialized — carrying device, OS, locale and session context — before any consent decision exists. That is the SDK’s documented contract, not an accident: it is what every shipped version has done, and it matches Amplitude/Mixpanel/Firebase.If you need a lawful basis before the first byte leaves the device (EU/UK GDPR, and similar), you must ask for it:

declare const apiKey: string;
declare const userGranted: boolean;

await AppDNA.configure(apiKey, 'production', { requireConsent: true });
// Nothing is emitted — not even `sdk_initialized` — until:
await AppDNA.setConsent(userGranted);

With requireConsent: true, a user who has never been asked is treated as denied. Nothing else in the SDK will hold the events back for you.

7. Change Log Level at Runtime

Adjust the log level without reconfiguring the SDK:

AppDNA.setLogLevel('debug');

Valid levels: 'none', 'error', 'warning', 'info', 'debug'.

8. Remote Config and Feature Flags

Retrieve server-side configuration values:

const welcomeMessage = await AppDNA.getRemoteConfig('welcome_message');

Check whether a feature flag is enabled:

const darkModeEnabled = await AppDNA.isFeatureEnabled('dark_mode');

9. Experiments

Get the variant assigned to a user for an experiment:

const variant = await AppDNA.getExperimentVariant('paywall_test');

Check if the user is in a specific variant:

const isInVariantB = await AppDNA.isInVariant('paywall_test', 'b');

Inspect all experiment exposures collected during the current session:

const exposures = await AppDNA.experiments.getExposures();
for (const exposure of exposures) {
  console.log(`${exposure.experimentId} → ${exposure.variant}`);
}

Each exposure is a Record<string, unknown> carrying experimentId and variant.

10. Session Data

Store cross-module session data that can be used in template interpolation across onboarding flows, paywalls, and in-app messages:

// Store session data — positional (key, value)
await AppDNA.session.set('selected_plan', 'premium');
await AppDNA.session.set('referral_code', 'FRIEND2026');

// Retrieve session data
const plan = await AppDNA.session.get('selected_plan'); // "premium"

// Clear the values set with session.set (reset() clears onboarding answers too)
await AppDNA.session.clear();

Session data values are accessible in Console-configured content using template syntax: {{session.selected_plan}}. See the Rich Media guide for the full template namespace ({{user.*}}, {{session.*}}, {{device.*}}, {{remote_config.*}}).

11. Entitlements

Check whether the user has any active subscription (StoreKit, Play Billing, RevenueCat, or web entitlement):

const isSubscribed = await AppDNA.billing.hasActiveSubscription();

Subscribe to live entitlement updates so your UI reflects renewals, cancellations, and restored purchases without polling:

const unsubscribe = AppDNA.billing.onEntitlementsChanged((entitlements) => {
  const active = entitlements.filter((e) => e.status === 'active');
  console.log(`Active entitlements: ${active.length}`);
});

See the Billing guide for the full purchase and restore flow.

12. Web Entitlement

Retrieve the current web entitlement (subscriptions granted outside the app store, e.g. via Stripe):

const ent = await AppDNA.getWebEntitlement();

Listen for web entitlement changes in real time:

const unsubscribe = AppDNA.onWebEntitlementChanged((ent) => {
  console.log('Web entitlement changed:', ent);
});

13. Deferred Deep Links

Check for a deferred deep link that brought the user to your app on first launch:

const link = await AppDNA.checkDeferredDeepLink();
if (link) {
  // Navigate to the linked content
}

14. Get SDK Version

Print the underlying native SDK version (useful for support tickets):

const version = await AppDNA.getSdkVersion();
console.log(`Native SDK version: ${version}`);

15. Reset on Logout

When a user signs out, call reset to clear the user identity and flush any remaining events:

await AppDNA.reset();

This clears the identified user, generates a new anonymous ID, and flushes queued events.

16. Shutdown

When the app is terminating, shut down the SDK to ensure all events are flushed and resources are released:

await AppDNA.shutdown();

On both iOS and Android this flushes queued events and releases native resources. The wrapper also detaches every delegate, veto handler, and cached config snapshot, so a later configure() starts clean.

You now have the SDK configured with user identification, event tracking, remote config, experiments, entitlements, and deep links working. Continue to the module-specific guides for Push Notifications, Billing, Onboarding, and Paywalls.

​1. Configure the SDK

​Configuration Options

​Environment

​Log Level

​Billing Provider

​2. Wait for Ready State

​3. Identify Users

​4. Track Events

​5. Flush Events Manually

​6. Set User Consent

​7. Change Log Level at Runtime

​8. Remote Config and Feature Flags

​9. Experiments

​10. Session Data

​11. Entitlements

​12. Web Entitlement

​13. Deferred Deep Links

​14. Get SDK Version

​15. Reset on Logout

​16. Shutdown

1. Configure the SDK

Configuration Options

Environment

Log Level

Billing Provider

2. Wait for Ready State

3. Identify Users

4. Track Events

5. Flush Events Manually

6. Set User Consent

7. Change Log Level at Runtime

8. Remote Config and Feature Flags

9. Experiments

10. Session Data

11. Entitlements

12. Web Entitlement

13. Deferred Deep Links

14. Get SDK Version

15. Reset on Logout

16. Shutdown