Flutter Rich Media

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

The AppDNA Flutter SDK renders rich media — Lottie animations, Rive animations, video, and images — through native platform pipelines on each side: SwiftUI + CoreAnimation on iOS, Jetpack Compose + Rive’s Android renderer on Android. Animations and effects look and feel identical to anything you would build by hand. All rich media content is configured in the AppDNA Console, no Dart code changes required.

Supported Formats

Lottie Animations

Lottie animations are rendered natively on both platforms. On iOS the SDK uses lottie-ios (added as a separate SPM dependency in your iOS host project), and on Android Lottie Compose is bundled directly into the AppDNA SDK.

Key	What it does	Unset
`lottie_url`	a URL to a `.json` or `.lottie` file	nothing is drawn — the block is gated on it
`autoplay`	plays as soon as it appears	`true`
`loop`	repeats	`true`
`lottie_speed`	playback rate	`1.0`
`lottie_width` / `lottie_height`	size in points; height falls back to the block’s `height`	the animation’s own width, `160` height
`play_on_scroll`	advances with the scroll position instead of with time	off
`play_on_tap`	plays once per tap rather than on appear	off

An animation comes from a URL, and its colours are baked into the file. There is no inline animation payload and no colour remapping: both were declared in the config models for a while, neither renderer ever read them, and they were removed rather than implemented. A remote .json or .lottie keeps the config a device downloads small, and a recolour belongs in the file the designer ships, where it can be seen before it is published.

Lottie is supported in onboarding content blocks, paywall sections, in-app message hero areas, and survey thank-you screens.

Rive Animations

Rive animations are rendered using the native Rive runtime on each platform. iOS requires adding rive-ios as a separate SPM dependency in your iOS host project. The Android Rive runtime is bundled with the AppDNA Android SDK.

Key	What it does	Unset
`rive_url`	a URL to a `.riv` file	nothing is drawn — the block is gated on it
`artboard`	which artboard to display	the file’s default artboard
`state_machine`	which state machine to run	the file’s default state machine
`autoplay`	plays as soon as it appears	`true`
`height`	size in points	`160`
`inputs`	state-machine inputs to set on appear — a bool sets a boolean input, a number sets a number input, anything else fires a trigger. (Android also accepts the older name `rive_inputs`.)	none set
`trigger_on_step_complete`	a trigger fired when the step completes	nothing is fired

Rive is supported in onboarding content blocks, paywall sections, in-app messages (both modal and fullscreen) and server-driven screens — everywhere Lottie is except surveys.

Video

Inline video playback uses native players on each platform — AVPlayer on iOS, ExoPlayer on Android. Flutter sees a fully rendered native view, so playback performance is identical to a hand-written native implementation.

Remote URL — provide a URL to an MP4 or HLS video
Thumbnail — optional poster image shown before playback
Controls — autoplay, loop, muted, show/hide controls
Sizing — configurable height and corner radius

Video is supported in onboarding content blocks, paywall sections, and in-app message hero areas.

Images

Remote images are fetched and cached by the native SDKs:

Remote URL — standard JPEG, PNG, and WebP supported on both platforms
GIF — animated GIFs are supported in in-app message hero areas and push notification rich content
SVG — supported on both platforms with native rasterization
Corner radius, sizing, content mode — configured in the Console

Asset URL Conventions

Each rich-media block in the AppDNA Console uses a typed URL field:

Field	Block type	Description
`lottie_url`	`lottie`	Remote URL to a `.json` Lottie animation
`rive_url`	`rive`	Remote URL to a `.riv` Rive animation
`video_url`	`video`	Remote URL to an MP4 or HLS video stream
`image_url`	`image`	Remote URL to a JPEG, PNG or WebP file. 🔴 SVG is not portable — Android decodes one and iOS cannot, so the console refuses an SVG upload
`video_thumbnail_url`	`video`	Optional poster image for the video block

🔴 A screen SECTION spells the poster thumbnail_url — without the video_ prefix — because the screens editor writes it that way. Content blocks and paywall sections use the prefixed name. Both renderers accept either spelling on either surface, so the prefixed one is always safe. Any of these fields can also accept inline data where supported (e.g. Lottie supports inline JSON). The SDK auto-detects the format from the URL extension or the inline payload.

Embedding Rich Media in Paywalls

Rich media inside paywalls is configured per section. The console exposes section types like paywall_header, paywall_features, and paywall_cta, each of which can host an image, Lottie animation, Rive animation, or video. The Flutter SDK simply presents the paywall and the native renderer handles the rest:

try {
  await AppDNA.paywall.present(
    "premium_upgrade",
    context: const PaywallContext(placement: "settings"),
  );
} catch (e) {
  print("Paywall not available: $e");
}

Common patterns:

Hero Lottie — attach a Lottie URL to the paywall_header section to play a looping product animation while the user reads features.
Feature illustrations — inside paywall_features, each feature row can carry an inline icon (Lucide / SF Symbols / Material / emoji) or a remote image.
Video proof — a short looping product demo can be embedded into a section with paywall_video style.
CTA pulse — the paywall_cta section supports CTA animations (pulse, glow, bounce) configured entirely from the Console.

Embedding Rich Media in Onboarding

Onboarding steps are composed of an ordered list of content blocks. Each block has a type and optional styling. Supported block types include:

Block Type	Description
`heading`	Styled heading (level 1-6)
`text`	Body text with styling
`image`	Remote image with corner radius and sizing
`button`	Action button (next, skip, link, permission)
`spacer`	Vertical spacing
`list`	Bullet, numbered, or checklist
`divider`	Horizontal separator
`badge`	Colored badge label
`icon`	Icon with emoji or icon reference
`toggle`	Switch with label and description
`video`	Inline video player
`lottie`	Lottie animation
`rive`	Rive animation

Blocks are added in the Console — the Flutter SDK simply presents the flow:

try {
  await AppDNA.onboarding.present("main_flow");
} catch (e) {
  print("Flow config not available: $e");
}

Embedding Rich Media in In-App Messages

In-app messages support a hero area at the top of the modal, banner, or fullscreen layout. The hero can host:

An image (with optional GIF playback)
A Lottie animation
A short looping video

The rest of the message body uses the same content block system as onboarding, so you can mix icons, badges, headings, text, and CTAs underneath the hero. In-app messages are triggered by event rules in the Console, but you can also gate display with an AppDNAInAppMessageDelegate:

class MyMessageObserver extends AppDNAInAppMessageDelegate {
  @override
  void onMessageShown(String messageId, String trigger) {
    print("Message shown: $messageId");
  }

  @override
  void onMessageAction(String messageId, String action, Map<String, dynamic>? data) {
    print("Message action: $action");
  }

  @override
  void onMessageDismissed(String messageId) {
    print("Message dismissed: $messageId");
  }

  @override
  bool shouldShowMessage(String messageId) {
    // Return false to suppress display.
    return true;
  }
}

AppDNA.inAppMessages.setDelegate(MyMessageObserver());

Animation Playback Control

All animation playback is configured per section / per content block in the AppDNA Console. The native renderers honor the data fields embedded in the config:

Field	Applies to	Description
`autoplay`	Lottie, Rive, video	Start playing as soon as the view is on screen
`loop`	Lottie, Rive, video	Loop playback indefinitely
`lottie_speed`	Lottie	Playback speed multiplier (e.g. `1.5`)
`muted`	Video	Mute audio
`video_controls`	Video	Show the native player chrome
`play_on_tap`	Lottie	Play once when the user taps the surface
`play_on_scroll`	Lottie	Tie progress to scroll position
`artboard`	Rive	Choose which artboard to display
`state_machine`	Rive	Name of the state machine to drive

🔴 The Console writes the video_*-prefixed names for the video fields — video_autoplay, video_loop, video_muted, video_controls — and those are the ones to look for in a published document. iOS also decodes the unprefixed autoplay / loop / muted / controls as a legacy fallback; Android reads the prefixed form only — so prefer the prefixed names whenever you inspect or hand-write a document. These fields are wired automatically by the renderer — you do not need to forward them through any Dart bridge.

Local Asset Embedding

Images only, and there is no asset:// URL form — an asset:// URL is treated as an ordinary URL, fails to fetch, and the block draws nothing. The scheme that exists is the relative appdna-assets/ path below, and it works on both platforms.

scripts/bundle-assets.ts in the AppDNA repo walks a downloaded config bundle, fetches the assets it references into an appdna-assets/ folder, and rewrites each URL to the relative path appdna-assets/<hash><ext>. Ship that folder inside your app — the iOS app bundle, or app/src/main/assets/ on Android — and the SDK loads each file from disk instead of the network, falling through to the remote URL when the file is not there. What it does not cover:

A path the build did not bundle falls through to the remote URL, on both platforms: the file is checked before the path is rewritten, so a partially bundled config degrades to the network rather than to broken images.
Only images resolve — the lookup ends in a UIImage, so a rewritten .json, .lottie, .riv, .mp4 or .mov path resolves on no platform. A config containing those should not be bundled: the remote URL that worked before bundling is replaced by a relative path that does not.

For a genuinely offline-first flow, keep the assets remote and rely on the HTTP caches described under Performance Notes. Flutter assets declared in pubspec.yaml are not visible to the native renderers, so put bundled rich media in the iOS / Android native locations described above.

Fallback Behavior

The native renderers degrade gracefully when an asset cannot be loaded:

Lottie / Rive — if the file is missing, malformed, or the network request fails, the block is skipped (no empty space, no crash). The next block in the layout takes its slot.
Video — if the video URL is unreachable, the optional thumbnail_url is shown instead. If no thumbnail is configured, the block is skipped.
Image — if the image URL is unreachable, the block is skipped. There is no broken-image placeholder.
Inline JSON Lottie — if the inline JSON is malformed, the block is skipped and a debug log is emitted.

All fallbacks are silent in release builds. In debug builds, the native SDKs emit warnings you can see in Xcode / Logcat.

Performance Notes

Lazy loading — rich-media blocks are loaded on demand. A Lottie / Rive / video asset is only fetched when its block enters the visible viewport.
Asset caching — remote assets are cached by the native HTTP stack (URLCache on iOS, OkHttp disk cache on Android). Subsequent presentations reuse the cached file.
Memory — the native renderers tear down decoded animations when the host view is dismissed, so animations do not accumulate memory across flows.
Cold start — avoid placing large video files on the very first onboarding step. Use a Lottie or static image for the welcome step and put video on later steps so playback starts after configuration is fully loaded.
Inline JSON — inline Lottie payloads add to the config bundle size. Prefer remote URLs for animations larger than ~50 KB to keep config refreshes fast.

Icons

The SDK supports structured icon references across all modules. Icons resolve to platform-native equivalents:

Library	Description	Example
`lucide`	Mapped to SF Symbols (iOS) / Material Icons (Android)	`"heart"`
`sf-symbols`	Native SF Symbols on iOS; mapped to Material on Android	`"star.fill"`
`material`	Native Material Icons on Android; mapped to SF Symbols on iOS	`"favorite"`
`emoji`	Unicode emoji characters	`"fire"`

Icons are used in onboarding content blocks, paywall feature lists, in-app message CTA buttons, and survey question options.

Visual Effects

Visual effects (haptics, particle effects, blur backdrops) are rendered by the native SDKs and configured in the Console. The Flutter SDK does not need any wiring — effects fire automatically based on the triggers attached to the section or step.

Haptic Feedback

Haptic feedback is triggered automatically based on Console configuration. Supported haptic types:

Type	Description
`light`	Subtle tap
`medium`	Medium tap
`heavy`	Strong tap
`selection`	Selection change feedback
`success`	Success notification
`warning`	Warning notification
`error`	Error notification

🔴 Nothing fires unless haptic.enabled is true. The config object gates every trigger, so a trigger set on its own does nothing — triggerIfEnabled returns early when the config is absent or not enabled, on both platforms. A type the SDK does not recognise is also ignored rather than falling back to a default. The triggers, each taking one of the types above:

Key	Fires when
`on_step_advance`	an onboarding step advances
`on_button_tap`	a button is tapped
`on_plan_select`	a paywall plan is selected
`on_option_select`	an option is chosen in a survey or form
`on_toggle`	a toggle changes
`on_form_submit`	a form is submitted
`on_error`	an error state is shown
`on_success`	a success state is shown

Particle Effects

Particle effects overlay the current screen. Supported effect types:

Type	Description
`confetti`	Colorful falling confetti
`sparkle`	Sparkling particles
`fireworks`	Burst effect
`snow`	Falling snowflakes
`hearts`	Floating hearts

Key	What it does	Unset
`type`	`confetti` · `sparkle` · `fireworks` · `snow` · `hearts`	`confetti`’s colours and glyph
`trigger`	`on_appear` · `on_step_complete` · `on_purchase` · `on_flow_complete`	`on_appear`
`duration_ms`	how long it runs	`2000`
`intensity`	`light` · `medium` · `heavy` — how many particles	the renderer’s own count
`colors`	an array of hex strings, replacing the type’s own palette	the palette for `type`

🔴 The surface decides when the trigger’s moment is, and each surface has only the moments it can actually hold. An effect whose trigger is not one of its surface’s moments has nothing to fire in, and nothing is drawn.

Where the effect is authored	The moments that surface has
an onboarding flow — `settings.particle_effect`	`on_appear` (the flow’s first step) · `on_step_complete` (each advance)
a paywall — `particle_effect`	`on_purchase`, after a successful purchase
a survey — `thankyou_particle_effect`	its thank-you screen. A survey has ONE moment, so the effect’s `trigger` is not consulted and the console no longer asks for it; a published value is still parsed and ignored
an in-app message — `particle_effect` on the message content	`on_appear`
a server-driven screen	`on_appear`

🔴 on_flow_complete is not an onboarding moment. The host takes the flow off the screen as soon as it completes, so an effect armed there would be dismissed in the frame it started. A celebration at the end of a flow belongs on whatever screen the app shows next.

Fixed in iOS 1.0.84 / Android 1.0.56. Before those versions only on_appear ever fired: the overlay re-checked the authored trigger after its parent had already decided to show it, and refused anything else. A paywall effect left on its Android default — on_purchase — therefore never ran at all.

Blur / Glassmorphism

Blur backdrops use the native platform’s high-performance blur primitive (iOS UIVisualEffectView, Android RenderEffect) for performant glassmorphism effects:

Radius — blur intensity
Tint — overlay color tint
Saturation — color saturation adjustment

Blur is supported as a backdrop for in-app message modals and fullscreen overlays.

Styling

All visual elements support fine-grained styling through the Console:

Text styles — font family, size, weight, color, alignment, line height, letter spacing, opacity
Backgrounds — solid color, linear/radial gradient, or remote image with overlay
Borders — width, color, style, and per-corner radius
Shadows — offset, blur, spread, and color
Spacing — per-side padding and margin
Animations — entry animations (slide, fade, scale), section stagger, CTA pulse/glow/bounce, dismiss animations

The native SDKs use platform-native fonts only. Custom web fonts are not supported. Specify system font families in the Console and the SDK will render them using each platform’s default typeface.

Dynamic Content Templates

Rich media content supports template interpolation using {{variable}} syntax. Available namespaces:

Namespace	Example	Source
`user.*`	`{{user.userId}}`	Identified user traits
`session.*`	`{{session.selected_plan}}`	App-defined session data
`onboarding.*`	`{{onboarding.step1.name}}`	Onboarding form responses
`computed.*`	`{{computed.custom_value}}`	Data from async hooks
`device.*`	`{{device.platform}}`	Device info (platform, OS, locale, country)
`remote_config.*`	`{{remote_config.app_name}}`	Remote config values
`input.*`	`{{input.first_name}}`	An onboarding answer by FIELD id alone, searching every step — the shorthand for `{{onboarding.<step>.<field>}}`

Use the pipe syntax for fallback values: {{user.name | there}} renders as "there" if the user name is not set or was identified as null.

No Dart Code Required

All rich media features are configured in the AppDNA Console. The Flutter SDK forwards a configuration ID to the native renderer, which handles all decoding, layout, and animation. You do not need to write any Dart code to use Lottie, Rive, video, haptics, particles, blur, icons, or content blocks.

​Supported Formats

​Lottie Animations

​Rive Animations

​Video

​Images

​Asset URL Conventions

​Embedding Rich Media in Paywalls

​Embedding Rich Media in Onboarding

​Embedding Rich Media in In-App Messages

​Animation Playback Control

​Local Asset Embedding

​Fallback Behavior

​Performance Notes

​Icons

​Visual Effects

​Haptic Feedback

​Particle Effects

​Blur / Glassmorphism

​Styling

​Dynamic Content Templates

​No Dart Code Required

Supported Formats

Lottie Animations

Rive Animations

Video

Images

Asset URL Conventions

Embedding Rich Media in Paywalls

Embedding Rich Media in Onboarding

Embedding Rich Media in In-App Messages

Animation Playback Control

Local Asset Embedding

Fallback Behavior

Performance Notes

Icons

Visual Effects

Haptic Feedback

Particle Effects

Blur / Glassmorphism

Styling

Dynamic Content Templates

No Dart Code Required