React Native API Reference

await AppDNA.configure('adn_live_xxx', 'production', { logLevel: 'debug', vetoTimeout: 5 });
await AppDNA.onReady();

AppDNA.track('screen_viewed', { screen: 'home' });
await AppDNA.setConsent(true);

await AppDNA.session.set('selected_plan', 'premium');
const plan = await AppDNA.session.get('selected_plan');

const location = await AppDNA.getLocationData('user_location');
console.log(location?.city, location?.country_code, location?.timezone_offset);

await AppDNA.remoteConfig.primeSnapshot();
const banner = AppDNA.remoteConfig.getCached('home_banner_text'); // synchronous, no bridge hop
const stop = AppDNA.remoteConfig.onChanged(() => console.log('config updated'));
stop();

interface AppDNAOnboardingDelegate {
  onOnboardingStarted(flowId: string): void;
  onOnboardingStepChanged(
    flowId: string,
    stepId: string,
    stepIndex: number,
    totalSteps: number,
  ): void;
  onOnboardingCompleted(flowId: string, responses: Record<string, unknown>): void;
  onOnboardingDismissed(flowId: string, atStep: number): void;
  /** Observe-only: fires after an onboarding permission resolves, however it resolved. */
  onPermissionResult(
    flowId: string,
    stepId: string,
    permissionType: string,
    granted: boolean,
  ): void;

  // ── Vetoes: native WAITS for these. See "Async Step Hooks" in the Onboarding guide. ──

  /** Return a StepAdvanceResult object. Default if you omit it: proceed (a sign-in action blocks). */
  onBeforeStepAdvance?(
    flowId: string,
    fromStepId: string,
    stepIndex: number,
    stepType: string,
    responses: Record<string, unknown>,
    stepData: Record<string, unknown> | undefined,
  ): Promise<Record<string, unknown>>;

  /** Return a StepConfigOverride object, or null to render unchanged. */
  onBeforeStepRender?(
    flowId: string,
    stepId: string,
    stepIndex: number,
    stepType: string,
    responses: Record<string, unknown>,
  ): Promise<Record<string, unknown> | null>;

  /** Return a live-state result, or null for no state change. */
  onElementInteraction?(
    flowId: string,
    stepId: string,
    blockId: string,
    action: string,
    value: string | undefined,
    inputValues: Record<string, unknown>,
  ): Promise<Record<string, unknown> | null>;

  /** Return `{ handledByHost: true, granted: boolean }` to short-circuit, or null to run the OS prompt. */
  onPermissionRequest?(permissionType: string): Promise<Record<string, unknown> | null>;
}

interface AppDNAPaywallDelegate {
  onPaywallPresented(paywallId: string): void;
  onPaywallAction(paywallId: string, action: string): void;
  onPaywallPurchaseStarted(paywallId: string, productId: string): void;
  onPaywallPurchaseCompleted(
    paywallId: string,
    productId: string,
    transaction: Record<string, unknown>,
  ): void;
  /**
   * `error` is the platform's error MESSAGE — a string, not an `Error` object: it crosses the bridge
   * as `localizedDescription` / `message`. `errorType` is the stable discriminator to branch on, and
   * `productId` is null only when no product had been selected.
   */
  onPaywallPurchaseFailed(
    paywallId: string,
    error: unknown,
    errorType: string,
    productId: string | null,
  ): void;
  onPaywallRestoreStarted(paywallId: string): void;
  onPaywallRestoreCompleted(paywallId: string, restoredProductIds: string[]): void;
  /** `error` is a message string, same as above. */
  onPaywallRestoreFailed(paywallId: string, error: unknown): void;
  onPaywallDismissed(paywallId: string): void;
  /** Post-purchase: the SDK asks you to open a deep-link URL configured in the Console. */
  onPostPurchaseDeepLink(paywallId: string, url: string): void;
  /** Post-purchase: the SDK asks you to continue to the next onboarding step. */
  onPostPurchaseNextStep(paywallId: string): void;

  /**
   * VETO. Validate a user-entered promo code: `true` applies it, `false` rejects it.
   * The one veto that defaults to **reject** — omit it, or time out, and every code is refused.
   */
  onPromoCodeSubmit?(paywallId: string, code: string): Promise<boolean>;
}

interface AppDNAPushDelegate {
  onPushTokenRegistered(token: string): void;
  onPushReceived(notification: Record<string, unknown>, inForeground: boolean): void;
  onPushTapped(notification: Record<string, unknown>, actionId: string | undefined): void;
}

interface AppDNABillingDelegate {
  /**
   * Also fires for purchases reported later (app start, `identify`, restore rescue, iOS interrupted /
   * Ask-to-Buy), at least once. Grant idempotently, keyed on `transaction.transactionId`.
   */
  onPurchaseCompleted(productId: string, transaction: Record<string, unknown>): void;
  /** `error` is a message string. */
  onPurchaseFailed(productId: string, error: unknown): void;
  /** Each map is an {@link Entitlement}. */
  onEntitlementsChanged(entitlements: Record<string, unknown>[]): void;
  onRestoreCompleted(restoredProductIds: string[]): void;
  /** Billing is permanently unavailable (Play Services missing/broken). **Android only** — never fires on iOS. */
  onBillingUnavailable(): void;
}

interface AppDNAInAppMessageDelegate {
  onMessageShown(messageId: string, trigger: string): void;
  onMessageAction(
    messageId: string,
    action: string,
    data: Record<string, unknown> | undefined,
  ): void;
  onMessageDismissed(messageId: string): void;
  /** VETO. Return `false` to suppress display — before view construction and before analytics. */
  shouldShowMessage(messageId: string): boolean | Promise<boolean>;
  /** @deprecated Native never emitted this. Use `onMessageShown`. */
  onMessagePresented?(messageId: string): void;
}

interface AppDNASurveyDelegate {
  onSurveyPresented(surveyId: string): void;
  /** `responses` is a LIST of `{questionId, answer}` maps — one per answered question. */
  onSurveyCompleted(surveyId: string, responses: Record<string, unknown>[]): void;
  onSurveyDismissed(surveyId: string): void;
  /** @deprecated Native never emitted this. Use `onSurveyCompleted`. */
  onSurveySubmitted?(surveyId: string, response: Record<string, unknown>): void;
}

interface AppDNADeepLinkDelegate {
  /** VETO. Return `false` to suppress deep-link processing (e.g. defer until the user signs in). */
  shouldOpen(url: string, params: Record<string, unknown>): boolean | Promise<boolean>;
  onDeepLinkReceived(url: string, params: Record<string, unknown>): void;
}

interface AppDNAScreenDelegate {
  onScreenPresented(screenId: string): void;
  onScreenDismissed(screenId: string, result: Record<string, unknown>): void;
  onFlowCompleted(flowId: string, result: Record<string, unknown>): void;
  /** VETO. Return `false` to intercept the action and prevent default handling. */
  onScreenAction(screenId: string, action: Record<string, unknown>): boolean | Promise<boolean>;
}

interface AppDNALifecycleDelegate {
  /** Fires once on idle → locked. `reason` is `billing_overdue`, `manual_admin`, or `org_cancelled`. `lockedAt` is ISO-8601. */
  onSdkRuntimeLocked(reason: string, lockedAt: string): void;
  /** Fires once on locked → idle. */
  onSdkRuntimeUnlocked(): void;
  /**
   * Fires for EVERY event the SDK tracks, with the properties sent with it, right after the event
   * is queued. Use it to forward AppDNA analytics into your own pipeline.
   */
  onEventTracked(name: string, properties: Record<string, unknown>): void;
  /**
   * Part of a published config could not be decoded and was DROPPED; the rest still renders.
   * `surface` is the kind (`onboarding_flow`, `paywall`, …), `id` the document when one is known,
   * and `detail` the CODING PATH and reason — e.g.
   * `steps[9].content_blocks[3]: Dictionary<String, Any> was null`.
   * Fires on the main thread, once per distinct problem per process.
   */
  onConfigurationIssue(surface: string, id: string | undefined, detail: string): void;
}

import type { StyleProp, ViewStyle } from 'react-native';

interface AppDNAScreenSlotProps {
  /** The Console slot name to render. */
  name: string;
  /** Height reserved before the first measurement lands. Defaults to 0. */
  minHeight?: number;
  /** Extra style. `height` is managed internally — do not set it here. */
  style?: StyleProp<ViewStyle>;
  /** Notified with the measured content height whenever it changes. */
  onContentSizeChange?: (size: { width: number; height: number }) => void;
}

type AppDNAEnvironment = 'production' | 'sandbox';

interface AppDNAOptions {
  /** Seconds between automatic event flushes. Not set: the bootstrap's value if positive, else 30. */
  flushInterval?: number;
  /** A cap on the network-sized batch. Not set: the bootstrap's value if positive, else no cap. Below 1 is ignored. */
  batchSize?: number;
  /** Remote-config cache TTL in seconds. Not set: the bootstrap's value if positive, else 3600. */
  configTTL?: number;
  /** Log verbosity. Default 'warning'. */
  logLevel?: AppDNALogLevel;
  /** Default 'storeKit2'. Read by BOTH natives — it was documented "iOS only" after Android gained it. */
  billingProvider?: AppDNABillingProvider;
  /**
   * Seconds a veto hook may take before native applies the hook's default. Default 5. Bounds the
   * host hooks on the bridge, except: `onBeforeStepAdvance` for a sign-in action waits at least 120 s
   * (`max(vetoTimeout, 120)`); a `refresh` interaction waits `max(vetoTimeout, 8)` and native drops
   * it after 8 s; native uses an `onBeforeStepRender` reply only if it arrives within 3 s.
   */
  vetoTimeout?: number;
  /** When true, analytics stay OFF — no event at all, not even `sdk_initialized` — until `setConsent(true)`. Default false. */
  requireConsent?: boolean;
  /** Android only: the notification small-icon drawable resource id. Ignored on iOS. */
  notificationIcon?: number;
}

type AppDNALogLevel = 'none' | 'error' | 'warning' | 'info' | 'debug';

type AppDNABillingProvider =
  | 'storeKit2'
  | 'revenueCat'
  | 'none'
  // Adapty carries its SDK key, so it crosses as a tagged object rather than a bare string.
  | { type: 'adapty'; apiKey: string };

await AppDNA.configure('adn_live_...', 'production', {
  // @ts-expect-error — bare 'adapty' won't type-check; it requires { type: 'adapty', apiKey: '...' }
  billingProvider: 'adapty',
});

type StepAdvanceResult =
  /** Continue to the next step normally. Also the default if you return anything else, except on a sign-in action, which then blocks. */
  | { type: 'proceed' }
  /** Continue and merge additional data into the session. */
  | { type: 'proceedWithData'; data: Record<string, unknown> }
  /** Block advancement and show an error message (red banner). */
  | { type: 'block'; message: string }
  /** Stay on the current step without advancing. A `message` renders a green success banner. */
  | { type: 'stay'; message?: string }
  /** Skip to a specific step by ID — optionally merging data on the way. */
  | { type: 'skipTo'; stepId: string; data?: Record<string, unknown> };

interface StepConfigOverride {
  /** Pre-fill form fields. Keys match the field IDs configured in the Console. */
  fieldDefaults?: Record<string, unknown>;
  title?: string;
  subtitle?: string;
  /** The primary CTA label. */
  ctaText?: string;
  /** Host-supplied Select options, keyed by block id. Replaces the removed `layoutOverrides`. */
  fieldOptions?: Record<string, Array<{ value: string; label: string; [key: string]: unknown }>>;
  /** Data your app supplies for this step, read in the Console as `{{hook_data.…}}`. */
  dataContext?: Record<string, unknown>;
  /** Host-supplied map routes, keyed by block id. */
  mapRoutes?: Record<string, { polyline?: string; stops?: Array<{ lat: number; lng: number; title?: string }> }>;
}

interface PaywallContext {
  /** Where the paywall was triggered. Included in every paywall analytics event. */
  placement?: string;
  /** Experiment ID forwarded to paywall analytics for slicing. */
  experiment?: string;
  /** Variant ID forwarded to paywall analytics for slicing. */
  variant?: string;
  /** Free-form bag forwarded to paywall analytics events. */
  customData?: Record<string, unknown>;
}

const PaywallAction = {
  ctaTapped: 'cta_tapped',
  featureSelected: 'feature_selected',
  planChanged: 'plan_changed',
  linkTapped: 'link_tapped',
  custom: 'custom',
} as const;

interface PushAction {
  id: string;
  label: string;
  action_type: string;
  action_value?: string;
}

interface PushPayload {
  push_id: string;
  title: string;
  body: string;
  image_url?: string;
  data?: Record<string, string>;
  /** The notification-body action, flattened. */
  action_type?: string;
  action_value?: string;
  /** The registered action BUTTONS. `onPushTapped(actionId)` identifies which was tapped —
   *  look it up here for its type/value/label. */
  actions?: PushAction[];
}

interface PushAction {
  id: string;
  label: string;
  action_type: string;
  action_value?: string;
}

interface Entitlement {
  identifier: string;   // both platforms (Android aliases it to productId)
  productId: string;    // both platforms
  isActive: boolean;    // both platforms — the question to ask
  expiresAt?: string;   // ISO 8601. OMITTED when there is no expiry: check `=== undefined`, not `null`
  store?: string;       // Android only
  status?: string;      // Android only — the server's subscription status, e.g. 'active' | 'trialing' | 'grace_period'
                        // | 'billing_retry' | 'on_hold' | 'pending' | 'paused' | 'expired' | 'canceled';
                        // isActive is true only for active, trialing and grace_period
  isTrial?: boolean;    // Android only
  offerType?: string;   // Android only
}

interface TransactionInfo {
  transactionId: string;   // App Store / Play transaction identifier
  productId: string;
  purchaseDate: string;    // Epoch milliseconds as a decimal string — parse with new Date(Number(tx.purchaseDate))
  environment: string;     // 'production' | 'sandbox' (iOS also reports 'xcode')
}

interface ProductInfo {
  id: string;
  name: string;
  description: string;
  displayPrice: string;      // Localized, store-formatted price — the string to render
  priceMicros: number;       // Price × 1,000,000, as an integer ($9.99 → 9990000)
  currencyCode?: string;     // ISO-4217. Android only
  isSubscription?: boolean;  // iOS only
  offerToken?: string;       // Android only — base-plan offer token, pass back to purchase()
}

interface WebEntitlement {
  isActive: boolean;
  planName?: string;
  priceId?: string;
  interval?: string;  // e.g. 'month', 'year'
  status: 'active' | 'trialing' | 'past_due' | 'canceled';
  /** Unix timestamp in SECONDS — a number, not an ISO string. */
  currentPeriodEnd?: number;
  /** Unix timestamp in seconds. */
  trialEnd?: number;
}

interface DeferredDeepLink {
  screen: string;
  params: Record<string, string>;
  visitorId: string;
}