iOS Rich Media & Animations

Supported on: iOS SDK 1.0.61+

The AppDNA iOS SDK supports rich media content across onboarding flows, paywalls, in-app messages, and surveys. All rich media is configured in the AppDNA Console — no code changes are needed to add animations, videos, or effects to your flows.

Supported Formats

Lottie Animations

Lottie animations render natively — lottie-ios is a dependency of AppDNASDK, so there is nothing to add to your own project.

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 messages (both modal and fullscreen), server-driven screens, and survey intro and thank-you screens.

Rive Animations

Rive animations render natively too — RiveRuntime is a dependency of AppDNASDK.

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 with native AVPlayer:

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.

Visual Effects

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 native UIVisualEffectView 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.

Asset URL Conventions

Each rich-media block carries its own typed URL field. The SDK picks the renderer from the block’s type, not from the file extension, so the field name is what matters:

Field	Block / section type	What it points at
`lottie_url`	`lottie`	a `.json` Lottie animation
`rive_url`	`rive`	a `.riv` Rive animation
`video_url`	`video`	an MP4 or an HLS stream
`image_url`	`image`	a JPEG, PNG or WebP. 🔴 SVG is not portable — Android decodes one and iOS cannot, so the console refuses an SVG upload and an SVG already published shows on Android and a placeholder on iOS. GIF renders as a static first frame on iOS
`video_thumbnail_url`	`video`	optional poster frame, drawn before playback

🔴 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 form is always safe.

Embedding Rich Media in Paywalls

Rich media inside a paywall belongs to a section. A section can host an image, a Lottie or Rive animation, or a video, and the SDK draws it when the paywall is presented — there is nothing to forward from your code:

Task {
    do {
        try await AppDNA.paywall.present(
            "premium_upgrade",
            context: PaywallContext(placement: "settings")
        )
    } catch {
        print("Paywall not available: \(error)")
    }
}

Common patterns:

Hero animation — a looping Lottie at the top of the paywall while the user reads the features.
Feature illustrations — each feature row can carry an SF Symbol, an emoji or a remote image.
Video proof — a short looping product demo in its own section.
CTA animation — pulse, glow and bounce are configured on the CTA section itself.

Embedding Rich Media in Onboarding

An onboarding step is an ordered list of content blocks. The rich-media types are image, video, lottie and rive; they sit alongside heading, text, button, list, badge, icon, toggle, divider and spacer in the same list and are laid out in order.

Task {
    do {
        try await AppDNA.onboarding.present("main_flow")
    } catch {
        print("Flow config not available: \(error)")
    }
}

Embedding Rich Media in In-App Messages

A modal, banner or fullscreen message has a hero area at the top, which can host an image (animated GIFs included), a Lottie animation or a short looping video. The body below the hero uses the same content-block system as onboarding. Messages are triggered by event rules in the Console. Implement AppDNAInAppMessageDelegate to observe them, or to suppress one:

final class MyMessageObserver: AppDNAInAppMessageDelegate {
    func onMessageShown(messageId: String, trigger: String) {}
    func onMessageAction(messageId: String, action: String, data: [String: Any]?) {}
    func onMessageDismissed(messageId: String) {}
    func shouldShowMessage(messageId: String) -> Bool { true }
}

AppDNA.inAppMessages.setDelegate(MyMessageObserver())

Animation Playback Control

Playback is authored per block in the Console; the renderer reads the fields off the published document and there is nothing to forward through your own code.

Field	Applies to	What it does
`autoplay`	Lottie	start as soon as the block is on screen (default on)
`loop`	Lottie	repeat indefinitely (default on)
`lottie_speed`	Lottie	playback speed multiplier, e.g. `1.5` (default `1.0`)
`play_on_tap`	Lottie	play once when the user taps it
`play_on_scroll`	Lottie	tie progress to scroll position
`artboard`	Rive	which artboard to display
`state_machine`	Rive	the state machine to drive
`video_autoplay`	Video	start on appear
`video_loop`	Video	repeat indefinitely
`video_muted`	Video	mute audio (default on)
`video_controls`	Video	show the native player chrome

🔴 Video fields are video_-prefixed and Lottie’s are not. autoplay and loop belong to Lottie; the video block’s equivalents are video_autoplay and video_loop. And Lottie’s speed is lottie_speed, not speed — a bare speed is a different field entirely (the particle background’s slow / normal / fast token), so authoring speed on a Lottie block does nothing. On iOS the unprefixed autoplay / loop / muted / controls are also decoded for the video block as a legacy fallback (ContentBlockTypes.swift). Android reads the prefixed form only, so prefer the prefixed names whenever you inspect or hand-write a document.

Local Asset Embedding

scripts/bundle-assets.ts in the AppDNA repo walks a downloaded config bundle, fetches the images 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 bundle and BundledImageResolver loads the file from disk instead of the network, falling through to the remote URL when the file is not there. 🔴 Images only, and there is no asset:// scheme. The lookup ends in a UIImage, so a rewritten .json, .lottie, .riv, .mp4 or .mov path resolves to nothing — a config containing those should not be bundled, because the remote URL that worked before bundling is replaced by a relative path that does not. Android resolves the same appdna-assets/ paths out of app/src/main/assets/, with the same images-only limit.

Performance Notes

Lazy loading — a rich-media block starts loading from its onAppear, so an asset on a later onboarding step is not fetched while the user is on the first.
Image caching — the SDK installs a 20 MB in-memory / 100 MB on-disk URLCache as URLCache.shared on first use, so AsyncImage reads and the SDK’s own prefetches share it. A host app that installs its own cache afterwards keeps that one.
Memory — players and animations are torn down when the host view disappears, so they do not accumulate across flows.
Cold start — avoid a large video on the very first onboarding step; use an image there and put video on a later step so playback starts after the config has settled.
File size — the config a device downloads carries the URL, not the animation, so a large .lottie costs a fetch rather than a bigger config. Keep it under a few hundred KB anyway: it is fetched on the step that draws it.

Icons

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

Library	Description	Example
`lucide`	Mapped to SF Symbols automatically; an unmapped name falls back to an emoji, then to a question-mark circle	`"heart"` -> `heart.fill`
`sf-symbols`	Native SF Symbols here; on Android the same name maps to the closest Material Icon, with an emoji fallback when unmapped — so it is safe to author for both	`"star.fill"`
`material`	Mapped to SF Symbols automatically; an unmapped name falls back to an emoji, then to a question-mark circle	`"favorite"` -> `heart.fill`
`emoji`	Unicode emoji characters	`"fire"` -> fire emoji

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

Content Blocks

Onboarding steps support rich content blocks that are rendered in order. Each block has a type and optional styling:

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

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 SDK uses platform-native fonts only. Custom web fonts are not supported. Specify system font families like .systemFont in the Console, and the SDK will render them natively.

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 Code Required

All rich media features are configured in the AppDNA Console. The SDK renders them automatically based on the config bundle. You do not need to write any code to use Lottie, Rive, video, haptics, particles, blur, icons, or content blocks.

​Supported Formats

​Lottie Animations

​Rive Animations

​Video

​Visual Effects

​Haptic Feedback

​Particle Effects

​Blur / Glassmorphism

​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

​Performance Notes

​Icons

​Content Blocks

​Styling

​Dynamic Content Templates

​No Code Required

Supported Formats

Lottie Animations

Rive Animations

Video

Visual Effects

Haptic Feedback

Particle Effects

Blur / Glassmorphism

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

Performance Notes

Icons

Content Blocks

Styling

Dynamic Content Templates

No Code Required