Flutter Surveys & Feedback

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

The surveys module lets you collect user feedback through in-app surveys. Surveys can trigger automatically based on events (like in-app messages) or be presented manually from your code.

How It Works

Surveys are configured in the Console with content, question types, and trigger rules. Like in-app messages, they can appear automatically when trigger conditions are met — no code required for trigger-based surveys.

Present a Survey Manually

await AppDNA.surveys.present("nps_q1_2026");

present returns once the survey request has been dispatched to the native SDK. Whether the survey actually appears depends on the survey’s status, audience, and trigger rules configured in the Console — the SDK fires the survey_shown analytics event (and your delegate’s onSurveyPresented callback) when it does. If you need to confirm that a survey was shown to the user, observe the delegate rather than the return value.

Module Access

final surveys = AppDNA.surveys;

Module Methods

Method	Signature	Description
`present`	`Future<void> present(String surveyId)`	Request that the SDK present a survey
`setDelegate`	`void setDelegate(AppDNASurveyDelegate?)`	Set a delegate for survey lifecycle callbacks

9 Question Types

Surveys support the following question types, configured in the Console:

Type	Display	Response
`nps`	0-10 numeric scale	Integer 0-10
`csat`	satisfaction scale, 3 / 5 / 7 wide	Integer 1-`scale`
`rating`	star, heart or thumb rating	Integer 1-`max`
`emoji_scale`	Emoji options	Selected emoji value
`yes_no`	Binary choice	Boolean
`single_choice`	Radio button options	Selected option string
`multi_choice`	Checkbox options	List of selected strings
`free_text`	Text input field	Free-form string
`likert`	numeric scale with optional anchor labels	Integer `min`-`max`

Question types and their content are defined entirely in the Console. The SDK renders them automatically based on the survey configuration.

scale is an accepted alias for likert, and scale_config for likert_config — both SDKs read either spelling, because questions were stored under the older one before likert became authorable. The Console writes the canonical names, so a survey created today uses likert and likert_config.A max above 10 is refused at authoring time: the scale draws as one un-scrolling row of fixed-width buttons, so a wider range would run off the edge of a phone. A min greater than max is read as the range the other way round rather than drawing nothing.

Question configuration

Each type reads its own config object on the question. Everything is optional; an unset value takes the default below.

Type	Config	Keys
`nps`	`nps_config`	`low_label`, `high_label` — the anchors under 0 and 10
`csat`	`csat_config`	`scale` (3, 5 or 7 — default 5), `labels` (one per point), `style`
`rating`	`rating_config`	`max` (default 5), `icon` — `star` (default), `heart` or `thumb`
`single_choice` · `multi_choice`	`choice_config`	`options`, each `{ id, label }`
`emoji_scale`	`emoji_config`	`emojis` — the scale, in order, worst to best. Default 😡 😕 😐 😊 😍
`free_text`	`free_text_config`	`placeholder`, `max_length` (default 500)
`likert`	`likert_config`	`min` (default 1), `max` (default 5, capped at 10), `low_label`, `high_label` — the anchors under the first and last button
any	—	`required` (default `false`), `image_url`, `show_if`

The emoji scale is read in order. The first entry is the worst and the last the best, and that order is what sentiment routing uses — see Follow-up actions. A scale of any length works.

Conditional questions

A question can carry a show_if naming an EARLIER question and the answers that reveal it:

{
  "id": "why_not",
  "type": "free_text",
  "text": "What would have made it better?",
  "show_if": { "question_id": "would_recommend", "answer_in": [false] }
}

The condition is re-evaluated after every answer, so the question appears and disappears as the respondent moves. Two rules worth knowing:

Unanswered means hidden. If the question it references has not been answered yet, the conditional question is not shown.
A blank question_id means no condition. A half-configured show_if shows the question rather than hiding it — otherwise a survey could render with nothing in it at all.

When a survey appears

trigger_rules on the survey decides this; no code is needed for a triggered survey.

Key	Effect
`event`	the event name that arms the survey — it is checked against every event the SDK sees
`conditions`	`[{ field, operator, value }]` over that event’s properties. Operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `in`, `not_in`. `in` / `not_in` take a list (a single value is treated as a one-element list). An operator outside this set never matches — it is a configuration error, and a survey that never appears is easier to notice than one shown to the wrong audience
`frequency`	`once` (default), `once_per_session`, `every_time`, `max_times`. A value outside this set behaves as `once` on both platforms
`max_displays`	the cap for `max_times`
`love_score_range`	`{ min, max }` against a love score held on the device. No SDK computes one yet (the value is always 0), so a `min` above 0 never shows the survey: leave it unset. A survey skipped by this rule (or by `min_sessions`) says so in the debug log.
`min_sessions`	the survey waits until the user has had this many sessions
`delay_seconds`	how long after the event to present

Presenting with present(...) from your own code ignores all of this except the survey’s own status and audience.

Follow-up actions

When a survey completes, the SDK classifies the FIRST answer as positive, negative or neutral, and runs the matching branch of follow_up_actions.

`survey_type`	positive	negative	neutral
`nps`	9-10	0-6	7-8
`csat`, `rating`	≥ 4	≤ 2	3
`emoji_scale`	above the middle of the authored scale	below it	the middle
anything else	—	—	always `neutral`

A numeric type whose answer is NOT a number falls through to the emoji row, so a csat survey whose first question is an emoji scale is classified by that scale rather than coming back neutral. An answer that is neither a number nor a member of the scale is always neutral.

Sentiment is read from the survey’s survey_type, not from the question’s type. A survey left as custom whose first question is an NPS scale is always neutral, and its branches never run. Set survey_type to match the first question.

Each branch is { action, message }:

`action`	What the SDK does
`prompt_review`	asks the OS for a store review prompt
`show_feedback_form`	opens a built-in free-text form, titled with `message`
`trigger_winback`	signals only — emits `survey_followup_winback` with the `message`, and your app launches the campaign
`dismiss`	nothing

A review prompt is never filtered by how someone answered. Apple’s App Review Guidelines and Google Play’s In-App Review policy both forbid asking the user a question — including one about their opinion — before presenting the rating prompt, and both forbid filtering who sees it by the answer.So: if any branch asks for prompt_review, every respondent who finishes the survey is eligible, whatever they answered, and the OS quota decides the rest. Putting prompt_review on one branch configures the ASKING, never the audience. The respondent’s own branch still runs, so a detractor routed to show_feedback_form sees the form as well.

Appearance

appearance on the survey:

Key	Values	Unset
`presentation`	`modal`, `bottom_sheet`, `fullscreen`	`modal`
`dismiss_allowed`	whether the respondent can close it	`true`
`show_progress`	a progress indicator across the questions	`false`
`corner_radius`	points	the platform default
`question_text_style`	a text style object for every question	inherited
`option_style`	an element style object for every choice row	inherited
`theme`	the colours and media below	—

appearance.theme may be a flat object, or { "light": { … }, "dark": { … } } — in the second form the active variant is sparse-merged over the other, so a dark theme only needs the keys it changes.

`theme` key	What it colours
`background_color`	the sheet
`text_color`	question text
`accent_color`	the selected option, the filled rating icon, the NPS selection
`button_color` · `button_text_color`	the submit button
`font_family` · `question_font_size` · `font_weight` · `text_align`	typography (`font_weight`: `normal`, `medium`, `semibold`, `bold`)
`gradient` · `button_gradient`	a gradient behind the sheet or the button

Plus the rich-media keys in the next section.

AppDNASurveyDelegate

All 3 methods on this delegate fire from the native survey pipeline alongside the existing analytics events. Register your delegate via AppDNA.surveys.setDelegate(...).

onSurveyPresented(surveyId) — fires when the survey view appears (alongside the survey_shown event).
onSurveyCompleted(surveyId, responses) — fires when the user submits the final question. responses is a List<Map<String, dynamic>> where each entry is an answer map of the shape {'questionId': String, 'answer': dynamic}, suitable for forwarding to your own analytics or CRM.
onSurveyDismissed(surveyId) — fires when the user closes the survey before completing it (X button, swipe-to-dismiss, outside tap).

Implement the delegate to capture survey responses and lifecycle events:

class FeedbackHandler extends AppDNASurveyDelegate {
  @override
  void onSurveyPresented(String surveyId) {
    print("Survey shown: $surveyId");
  }

  @override
  void onSurveyCompleted(String surveyId, List<Map<String, dynamic>> responses) {
    // `responses` is a list of answer maps: {'questionId': String, 'answer': dynamic}.
    dynamic answerFor(String questionId) => responses
        .firstWhere((r) => r["questionId"] == questionId, orElse: () => {})["answer"];

    final score = answerFor("nps_question") as int?;
    if (score != null) {
      if (score >= 9) {
        showReferralPrompt();
      } else if (score <= 6) {
        showSupportLink();
      }
    }
    final feedback = answerFor("free_text_question") as String?;
    if (feedback != null) {
      print("User feedback: $feedback");
    }
  }

  @override
  void onSurveyDismissed(String surveyId) {
    print("Survey dismissed: $surveyId");
  }
}

AppDNA.surveys.setDelegate(FeedbackHandler());

Response Shape

The responses list passed to onSurveyCompleted holds one answer map per answered question, each of the shape {'questionId': String, 'answer': dynamic}. The answer value type follows the question type:

Question Type	`answer` Type
`nps`, `csat`, `rating`	`int`
`yes_no`	`bool`
`single_choice`, `emoji_scale`, `free_text`	`String`
`multi_choice`	`List<String>`

Rich Media

Survey questions support rich media content configured in the Console:

Key	On	What it does
`questions[].image_url`	a question	an image above the question text
`theme.intro_lottie_url`	the survey	a Lottie played once before the first question
`theme.thankyou_lottie_url`	the survey	a Lottie on the thank-you screen
`theme.thankyou_particle_effect`	the survey	a particle effect on the thank-you screen — see Rich Media for its keys
`theme.thank_you_text`	the survey	replaces “Thank you!”; supports template interpolation
`theme.blur_backdrop`	the survey	`{ radius, tint, saturation }` behind the sheet
`theme.haptic`	the survey	`{ enabled, triggers: { on_option_select, on_button_tap, … } }`

Option icons are not authorable. choice_config.options[] accepts an icon through the API and the survey editor has no control for it, so it cannot be set from the Console; it renders on iOS and not on Android. Treat choice options as { id, label } until that is resolved.

See the Rich Media guide for the Lottie, particle and haptic key tables, and for which formats each platform plays.

Auto-Tracked Events

Every event whose name begins survey_ carries survey_id. The two feedback_form_* events are emitted by the form itself and carry only the fields named below.

Event	Trigger
`survey_shown`	A survey is displayed
`survey_question_answered`	Each individual answer, as it is given
`survey_completed`	The final answer is submitted. Carries `survey_type` and the full `answers` array
`survey_dismissed`	Closed before completing
`survey_followup_prompt_review`	A follow-up asked the OS for a store review prompt. Carries `sentiment`
`survey_followup_feedback_form`	A follow-up opened the built-in feedback form. Carries `sentiment`
`survey_followup_winback`	A follow-up signalled a win-back. Carries `sentiment` and `message`
`feedback_form_submitted`	The feedback form was submitted. Carries `feedback`
`feedback_form_dismissed`	The feedback form ended without a submission. Carries `reason`

feedback_form_submitted / feedback_form_dismissed come from the survey follow-up form — the one follow_up_actions opens. There is no separate standalone form.reason on the dismissal is user (the Cancel button; on Android also a back press or a tap outside the dialog) or presenter_released (the host navigated away and the form went with it — a form the user never saw, which would otherwise be counted as one they closed).

Full Example

import 'package:appdna_sdk/appdna_sdk.dart';

class FeedbackManager extends AppDNASurveyDelegate {
  FeedbackManager() {
    AppDNA.surveys.setDelegate(this);
  }

  /// Present NPS survey after a key moment
  Future<void> askForFeedback() async {
    await AppDNA.surveys.present("nps_q1_2026");
  }

  @override
  void onSurveyPresented(String surveyId) {
    // Survey is visible
  }

  @override
  void onSurveyCompleted(String surveyId, List<Map<String, dynamic>> responses) {
    // `responses` is a list of answer maps: {'questionId': String, 'answer': dynamic}.
    final nps = responses.firstWhere(
      (r) => r["questionId"] == "nps_question",
      orElse: () => {},
    );
    final score = nps["answer"] as int?;
    if (score == null) return;

    if (score >= 9) {
      showReferralPrompt();
    } else if (score <= 6) {
      showSupportLink();
    }
  }

  @override
  void onSurveyDismissed(String surveyId) {
    // User dismissed without responding
  }
}

Surveys are created in the Console under Feedback > Surveys. Trigger-based surveys appear automatically — manual presentation with present() is for cases where you want precise control over timing.

​How It Works

​Present a Survey Manually

​Module Access

​Module Methods

​9 Question Types

​Question configuration

​Conditional questions

​When a survey appears

​Follow-up actions

​Appearance

​AppDNASurveyDelegate

​Response Shape

​Rich Media

​Auto-Tracked Events

​Full Example

How It Works

Present a Survey Manually

Module Access

Module Methods

9 Question Types

Question configuration

Conditional questions

When a survey appears

Follow-up actions

Appearance

AppDNASurveyDelegate

Response Shape

Rich Media

Auto-Tracked Events

Full Example