Flutter Screens

Supported on: iOS SDK 1.0.61+ · Android SDK 1.0.33+ · Flutter SDK 1.0.3+

Overview

Server-driven screens let growth teams design and deploy native screens from the AppDNA Console without an app release. Screens are composed from the same content-block and section library used by paywalls, onboarding, in-app messages, and surveys, then delivered to the SDK via the remote config bundle. On Flutter, screens are rendered fully natively — SwiftUI on iOS and Jetpack Compose on Android — so the experience matches a hand-built native UI. Use screens to ship feature announcements, upgrade prompts, referral surfaces, guided tutorials, and other composable native surfaces from the Console.

Show a Screen

final result = await AppDNA.screen.show("upgrade_prompt");
if (result.dismissed) {
  print("User dismissed");
} else {
  print("Responses: ${result.responses}");
}

AppDNA.screen.show(...) returns a ScreenResult with dismissed (bool) and responses (Map). Lifecycle (onScreenPresented, onScreenAction, onScreenDismissed) also flows to the delegate registered via setDelegate(...) — see Screen Delegate below.

Show a Multi-Screen Flow

final result = await AppDNA.screen.showFlow("onboarding_v2");
if (result.completed) {
  print("Completed: ${result.screensViewed.length} screens — ${result.screensViewed.join(' → ')}");
} else {
  print("Abandoned at screen ${result.lastScreenId}");
}

AppDNA.screen.showFlow(...) returns a FlowResult with completed (bool), screensViewed (List<String> — ordered screen IDs viewed), lastScreenId (String?), and responses (Map). Multi-screen flows step through the screens you configured in the Console; the delegate’s onFlowCompleted also fires when the user finishes or abandons.

Dismiss

await AppDNA.screen.dismiss();

Screen Slots (Inline Content)

Place named slots in your app; the Console assigns screens to slots and the SDK renders them inline at runtime. Slots are addressed by ID and resolved on every config refresh.

Empty slots render nothing — no visual impact.
Content updates on the next config refresh.
Supports audience targeting per slot.

Slot IDs are configured in the AppDNA Console and rendered through the bundled native renderer at the matching screen-slot widget in your app. Inject screens automatically between app navigations:

// Intercept every navigation
await AppDNA.screen.enableNavigationInterception();

// Or scope to specific routes (exact match or wildcard suffix)
await AppDNA.screen.enableNavigationInterception(
  forScreens: ["SettingsPage", "Premium*"],
);

// To stop intercepting
await AppDNA.screen.disableNavigationInterception();

When interception is enabled, the SDK consults the registered AppDNAScreenDelegate on every navigation event so you can route or suppress as needed. Pass forScreens to limit interception to a specific allowlist — supports exact route names and trailing * wildcards.

Debug Preview

Render a screen from raw JSON for design or QA preview without publishing to the Console:

await AppDNA.screen.preview({
  "id": "test",
  "name": "Test",
  "presentation": "modal",
  "layout": {"type": "scroll"},
  "sections": [/* ... */],
});

Use during development only.

Module Access

Access the screen module through the AppDNA.screen namespace:

final screen = AppDNA.screen;

Method	Signature	Description
`show`	`Future<ScreenResult> show(String screenId, { Map<String, dynamic>? context })`	Present a server-driven screen by ID. Returns a `ScreenResult`.
`showFlow`	`Future<FlowResult> showFlow(String flowId, { Map<String, dynamic>? context })`	Present a multi-screen flow. Returns a `FlowResult`.
`dismiss`	`Future<void> dismiss()`	Dismiss the currently-presented screen
`enableNavigationInterception`	`Future<void> enableNavigationInterception({List<String>? forScreens})`	Inject screens between app navigations. Pass `forScreens` to scope to a specific allowlist (exact match or trailing `*` wildcard).
`disableNavigationInterception`	`Future<void> disableNavigationInterception()`	Stop intercepting navigation
`preview`	`Future<void> preview(Map<String, dynamic> json)`	Render a screen from raw JSON for debugging
`setDelegate`	`void setDelegate(AppDNAScreenDelegate? delegate)`	Observe screen lifecycle from your Dart app

Audience-Based Presentation

In addition to imperative show(...) calls, screens can be presented automatically by Console-driven audience targeting:

Design the screen in the AppDNA Console.
Attach a trigger (event-based, schedule-based, or app-state-based) and an audience.
Publish the screen.

When a user enters the audience, the SDK fetches the latest config bundle and presents the screen at the configured trigger point. The required wiring is minimal:

Call AppDNA.configure(...) at app startup.
Identify the user with AppDNA.identify(...) so targeting rules can resolve.
Track relevant events with AppDNA.track(...) so event triggers can fire.

Lifecycle callbacks fire on the registered delegate either way.

Screen Delegate

AppDNAScreenDelegate exposes the four screen lifecycle methods. The delegate is implemented as a Dart class and registered with the module:

import 'package:appdna_sdk/appdna_sdk.dart';

class MyScreenObserver implements AppDNAScreenDelegate {
  @override
  void onScreenPresented(String screenId) {
    print("Screen shown: $screenId");
  }

  @override
  void onScreenDismissed(String screenId, Map<String, dynamic> result) {
    final dismissed = result["dismissed"] as bool? ?? false;
    final responses = (result["responses"] as Map?)?.cast<String, dynamic>();
    final lastAction = result["last_action"] as String?;
    print("Screen $screenId dismissed=$dismissed, action=$lastAction");
  }

  @override
  void onFlowCompleted(String flowId, Map<String, dynamic> result) {
    final completed = result["completed"] as bool? ?? false;
    final screensViewed = (result["screens_viewed"] as List?)?.cast<String>() ?? const [];
    print("Flow $flowId completed=$completed, screens=$screensViewed");
  }

  @override
  bool onScreenAction(String screenId, Map<String, dynamic> action) {
    final type = action["type"] as String?;
    print("Screen $screenId action: $type");
    // Return false to intercept the action and apply custom handling.
    return true;
  }
}

AppDNA.screen.setDelegate(MyScreenObserver());

Pass null to clear the delegate and stop listening:

AppDNA.screen.setDelegate(null);

Delegate Method Reference

Method	Description
`onScreenPresented`	Fires when a screen appears, alongside the `screen_presented` analytics event.
`onScreenDismissed`	Fires when a screen is dismissed. `result` carries dismissal context (e.g. `dismissed`, `responses`, `last_action`, `duration_ms`).
`onFlowCompleted`	Fires when a multi-screen flow ends. `result["completed"]` is `true` when the user reached the final screen, `false` when abandoned.
`onScreenAction`	Fires for every section action the user takes on a screen. Return `false` from your override to intercept the action; return `true` to let the SDK apply its default handling.

Result and action payloads are delivered as Map<String, dynamic> rather than typed Dart classes. This keeps the bridge forward-compatible with new fields the native SDKs add (for example, additions like last_action or duration_ms) without requiring a Flutter package bump.

Sections and Content Blocks

Screens are composed of an ordered list of sections. Each section pulls from the unified registry shared across all SDK modules, so the same content blocks you use in paywalls, onboarding, in-app messages, and surveys are available inside screens:

Category	Section Types
Generic	`content_blocks`, `hero`, `spacer`, `divider`, `cta_footer`, `sticky_footer`
Onboarding	`onboarding_step`, `progress_indicator`, `navigation_controls`
Paywall	`paywall_header`, `paywall_plans`, `paywall_cta`, `paywall_features`, and more
Survey	`survey_question`, `survey_nps`, `survey_csat`, `survey_rating`, `survey_free_text`, `survey_thank_you`
Message	`message_banner`, `message_modal`, `message_content`
Media	`image_section`, `video_section`, `lottie_section`, `rive_section`

Sections are assembled in the Console and stream to the SDK through the config bundle. The Flutter SDK does not need to know which sections a screen contains — the native renderer reads the configuration and lays the screen out.

Presentation Modes

Screens support several presentation modes configured per screen in the Console. The native renderer honors each mode on the appropriate platform:

Mode	Description
`fullscreen`	Full-screen modal covering the entire screen (default).
`modal`	Standard modal sheet (page sheet style on iOS / Android).
`bottom_sheet`	Draggable bottom sheet.
`push`	Navigation push on iOS (within a navigation controller).

Unrecognized values fall through to fullscreen on Android. The Flutter SDK does not need to pick a mode — the Console controls the presentation per screen.

Auto-Tracked Events

The native SDKs emit standard analytics events for every screen interaction. These events flow through the same event pipeline as other AppDNA events:

Event	When
`screen_presented`	Screen appears
`screen_dismissed`	Screen disappears
`screen_action`	User taps a CTA inside a screen
`flow_started`	Multi-screen flow begins
`flow_completed`	Multi-screen flow finishes
`flow_abandoned`	Multi-screen flow dismissed early
`slot_rendered`	A named screen slot displays content
`slot_registered`	A named screen slot first renders
`interception_triggered`	Native navigation interception fires

You do not need to forward or duplicate these events from Dart — the native SDK already emits them.

Configuration in Console

Each screen is configured in the AppDNA Console with:

Screen ID — the canonical identifier used by audience triggers and analytics events.
Layout — scroll, stack, or grid container that wraps the section list.
Sections — an ordered list pulled from the unified section registry.
Presentation — fullscreen, modal, bottom_sheet, or push.
Trigger — event-based (event_name matching), schedule-based (cron-style), or app-state-based.
Audience — targeting rules across user traits, device info, remote config, computed values, and experiment exposures.
Style — per-screen theme, typography overrides, brand colors, and animation defaults.

Publish the screen and it is delivered to all SDKs on the next config refresh.

Full Example

import 'package:appdna_sdk/appdna_sdk.dart';

class ScreenCoordinator implements AppDNAScreenDelegate {
  void start() {
    AppDNA.screen.setDelegate(this);
  }

  void stop() {
    AppDNA.screen.setDelegate(null);
  }

  @override
  void onScreenPresented(String screenId) {
    print("Screen shown: $screenId");
  }

  @override
  void onScreenDismissed(String screenId, Map<String, dynamic> result) {
    final purchased = (result["responses"] as Map?)?["purchased"] == true;
    if (purchased) {
      _unlockPremium();
    }
  }

  @override
  void onFlowCompleted(String flowId, Map<String, dynamic> result) {
    final screens = (result["screens_viewed"] as List?)?.cast<String>() ?? const [];
    print("Flow $flowId completed, screens viewed: $screens");
  }

  @override
  bool onScreenAction(String screenId, Map<String, dynamic> action) {
    final type = action["type"] as String?;
    print("Screen $screenId action: $type");
    return true;
  }

  void _unlockPremium() {
    // Grant access in your own state management.
  }
}

Wire it into your app startup:

final coordinator = ScreenCoordinator();

Future<void> bootstrap() async {
  await AppDNA.configure(apiKey: "YOUR_API_KEY");
  await AppDNA.identify("user-123");
  coordinator.start();
}

Screens are delivered via the same Firestore-backed config bundle as other SDK modules. Ensure your app has network access on first launch to fetch the latest screen configurations. After the first successful fetch, the native SDKs cache the bundle and continue rendering screens offline.

​Overview

​Show a Screen

​Show a Multi-Screen Flow

​Dismiss

​Screen Slots (Inline Content)

​Navigation Interception

​Debug Preview

​Module Access

​Audience-Based Presentation

​Screen Delegate

​Delegate Method Reference

​Sections and Content Blocks

​Presentation Modes

​Auto-Tracked Events

​Configuration in Console

​Full Example

Overview

Show a Screen

Show a Multi-Screen Flow

Dismiss

Screen Slots (Inline Content)

Navigation Interception

Debug Preview

Module Access

Audience-Based Presentation

Screen Delegate

Delegate Method Reference

Sections and Content Blocks

Presentation Modes

Auto-Tracked Events

Configuration in Console

Full Example