> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appdna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flutter Screens

> Observe server-driven screens designed in the AppDNA Console, rendered natively

<Info>
  **Supported on:** iOS SDK `1.0.61+` · Android SDK `1.0.33+` · Flutter SDK `1.0.3+`
</Info>

## 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

```dart theme={null}
await AppDNA.screen.show("upgrade_prompt");
```

`AppDNA.screen.show(...)` returns `Future<void>` — it presents the screen and completes once the native surface has been handed off. The outcome (dismissal, responses, actions) arrives through the delegate registered via `setDelegate(...)`: `onScreenPresented`, `onScreenAction`, `onScreenDismissed` — see [Screen Delegate](#screen-delegate) below.

## Show a Multi-Screen Flow

```dart theme={null}
await AppDNA.screen.showFlow("onboarding_v2");
```

`AppDNA.screen.showFlow(...)` returns `Future<void>`. Multi-screen flows step through the screens you configured in the Console; the result arrives on the delegate's `onFlowCompleted` callback, which fires when the user finishes or abandons the flow.

## Dismiss

```dart theme={null}
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.

## Navigation Interception

Inject screens automatically between app navigations:

```dart theme={null}
// Enable interception
await AppDNA.screen.enableNavigationInterception();

// 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. `enableNavigationInterception()` takes no arguments.

## Debug Preview

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

```dart theme={null}
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:

```dart theme={null}
final screen = AppDNA.screen;
```

| Method                          | Signature                                                                 | Description                                                                             |
| ------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `show`                          | `Future<void> show(String screenId, { Map<String, dynamic>? context })`   | Present a server-driven screen by ID. The result arrives on the delegate.               |
| `showFlow`                      | `Future<void> showFlow(String flowId, { Map<String, dynamic>? context })` | Present a multi-screen flow. The result arrives on `onFlowCompleted`.                   |
| `dismiss`                       | `Future<void> dismiss()`                                                  | Dismiss the currently-presented screen                                                  |
| `enableNavigationInterception`  | `Future<void> enableNavigationInterception()`                             | Inject screens between app navigations. Takes no arguments.                             |
| `disableNavigationInterception` | `Future<void> disableNavigationInterception()`                            | Stop intercepting navigation                                                            |
| `preview`                       | `Future<Map<String, dynamic>?> preview(Map<String, dynamic> json)`        | Render a screen from raw JSON for debugging. Returns the preview result map, or `null`. |
| `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:

1. Design the screen in the AppDNA Console.
2. Attach a trigger (event-based, schedule-based, or app-state-based) and an audience.
3. 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:

```dart theme={null}
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:

```dart theme={null}
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

```dart theme={null}
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:

```dart theme={null}
final coordinator = ScreenCoordinator();

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

<Note>
  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.
</Note>