Surveys

import 'package:nexus_flutter/nexus.dart';

NexusSurveysCopy Anchor Link

In-product surveys. Fetches the surveys a user is eligible for, decides which to show (auto-show for popover/banner types + event triggers), and submits answers. The rendering is done by NexusSurveyOverlay (default UI) or your own widget driven by NexusSurveyController.

activeCopy Anchor Link

List<NexusSurvey> get active

All surveys the user is currently eligible for.

currentCopy Anchor Link

final ValueNotifier<NexusSurvey?> current

The survey currently requested to display (null when none). The overlay listens to this.

fetch()Copy Anchor Link

Future<List<NexusSurvey>> fetch()

Fetch eligible surveys from the server (targeting/sampling/capping applied).

Returns Future<List<NexusSurvey>>

onEvent()Copy Anchor Link

void onEvent(String name)

Called when an analytics event fires — shows a survey gated on that event.

Parameters

show()Copy Anchor Link

void show(NexusSurvey survey)

Present a specific survey now (e.g. from a "Give feedback" button).

Parameters

close()Copy Anchor Link

void close()

Remove the current survey from the screen (called by the UI when done).

byId()Copy Anchor Link

NexusSurvey? byId(String id)

Parameters

Returns NexusSurvey?

respond()Copy Anchor Link

Future<void> respond(NexusSurvey survey, Map<String, Object?> answers, {bool completed = false, bool dismissed = false})

Submit a response (partial, complete, or dismissed). Best-effort.

Parameters

dispose()Copy Anchor Link

void dispose()

NexusSurveyChoiceCopy Anchor Link

NexusSurveyChoiceCopy Anchor Link

const NexusSurveyChoice({required this.value, this.label, this.open = false})

Parameters

fromJson()Copy Anchor Link

static NexusSurveyChoice fromJson(dynamic json)

Parameters

Returns NexusSurveyChoice

displayCopy Anchor Link

String get display

valueCopy Anchor Link

final String value

labelCopy Anchor Link

final String? label

openCopy Anchor Link

final bool open

NexusSurveyQuestionCopy Anchor Link

NexusSurveyQuestionCopy Anchor Link

const NexusSurveyQuestion({required this.id, required this.type, required this.label, this.description, this.required = false, this.choices = const [], this.display, this.scaleMin, this.scaleMax, this.lowerLabel, this.upperLabel, this.buttonText, this.buttonUrl})

Parameters

fromJson()Copy Anchor Link

static NexusSurveyQuestion fromJson(Map<String, dynamic> m)

Parameters

Returns NexusSurveyQuestion

isMultiSelectCopy Anchor Link

bool get isMultiSelect

typeCopy Anchor Link

final String type

open | single_choice | multiple_choice | rating | nps | boolean | link | email

idCopy Anchor Link

final String id

labelCopy Anchor Link

final String label

descriptionCopy Anchor Link

final String? description

requiredCopy Anchor Link

final bool required

choicesCopy Anchor Link

final List<NexusSurveyChoice> choices

displayCopy Anchor Link

final String? display

scaleMinCopy Anchor Link

final int? scaleMin

scaleMaxCopy Anchor Link

final int? scaleMax

lowerLabelCopy Anchor Link

final String? lowerLabel

upperLabelCopy Anchor Link

final String? upperLabel

buttonTextCopy Anchor Link

final String? buttonText

buttonUrlCopy Anchor Link

final String? buttonUrl

NexusSurveyTriggerCopy Anchor Link

NexusSurveyTriggerCopy Anchor Link

const NexusSurveyTrigger({this.events = const [], this.delaySeconds, this.minInterval, this.selector})

Parameters

fromJson()Copy Anchor Link

static NexusSurveyTrigger? fromJson(Map<String, dynamic>? m)

Parameters

Returns NexusSurveyTrigger?

eventsCopy Anchor Link

final List<String> events

delaySecondsCopy Anchor Link

final int? delaySeconds

minIntervalCopy Anchor Link

final int? minInterval

selectorCopy Anchor Link

final String? selector

NexusSurveyCopy Anchor Link

NexusSurveyCopy Anchor Link

const NexusSurvey({required this.id, required this.name, required this.type, required this.questions, this.appearance = const {}, this.trigger, this.iterationKey, this.resumeResponseId, this.resumeAnswers = const {}})

Parameters

fromJson()Copy Anchor Link

static NexusSurvey fromJson(dynamic json)

Parameters

Returns NexusSurvey

positionCopy Anchor Link

String? get position

primaryColorHexCopy Anchor Link

String? get primaryColorHex

thankYouTitleCopy Anchor Link

String? get thankYouTitle

thankYouMessageCopy Anchor Link

String get thankYouMessage

showThankYouCopy Anchor Link

bool get showThankYou

showProgressBarCopy Anchor Link

bool get showProgressBar

submitButtonTextCopy Anchor Link

String? get submitButtonText

idCopy Anchor Link

final String id

nameCopy Anchor Link

final String name

typeCopy Anchor Link

final String type

questionsCopy Anchor Link

final List<NexusSurveyQuestion> questions

appearanceCopy Anchor Link

final Map<String, Object?> appearance

triggerCopy Anchor Link

final NexusSurveyTrigger? trigger

iterationKeyCopy Anchor Link

final String? iterationKey

resumeResponseIdCopy Anchor Link

final String? resumeResponseId

resumeAnswersCopy Anchor Link

final Map<String, Object?> resumeAnswers

SurveySubmitCopy Anchor Link

typedef SurveySubmit = Future<void> Function(NexusSurvey survey, Map<String, Object?> answers, {bool completed, bool dismissed})

Persists a response (partial or terminal). Wired to the surveys service.

NexusSurveyControllerCopy Anchor Link

class NexusSurveyController extends ChangeNotifier

Drives one survey: holds answers, step position, validity, and submit/dismiss.

This is the seam for custom UIs — pass your own widget to the overlay and drive it entirely from this controller (currentQuestion, setAnswer, next, back, complete, dismiss, progress). It's a ChangeNotifier, so rebuild on changes.

stepCopy Anchor Link

int get step

totalStepsCopy Anchor Link

int get totalSteps

isDoneCopy Anchor Link

bool get isDone

isSubmittingCopy Anchor Link

bool get isSubmitting

progressCopy Anchor Link

double get progress

isLastCopy Anchor Link

bool get isLast

currentQuestionCopy Anchor Link

NexusSurveyQuestion? get currentQuestion

canAdvanceCopy Anchor Link

bool get canAdvance

Whether the current (required) question has a valid answer.

surveyCopy Anchor Link

final NexusSurvey survey

onCloseCopy Anchor Link

VoidCallback? onClose

Wired by the overlay to remove the survey from the screen. Call close from your UI when you're done presenting (e.g. after a thank-you).

answersCopy Anchor Link

final Map<String, Object?> answers

Answers keyed by question id (value type depends on question type).

close()Copy Anchor Link

void close()

answerFor()Copy Anchor Link

Object? answerFor(String questionId)

Parameters

Returns Object?

setAnswer()Copy Anchor Link

void setAnswer(String questionId, Object? value)

Parameters

toggleChoice()Copy Anchor Link

void toggleChoice(String questionId, String value)

Toggle a value within a multi-select answer.

Parameters

next()Copy Anchor Link

Future<void> next()

Advance to the next question, or complete on the last.

back()Copy Anchor Link

void back()

complete()Copy Anchor Link

Future<void> complete()

dismiss()Copy Anchor Link

Future<void> dismiss()

NexusQuestionBuilderCopy Anchor Link

typedef NexusQuestionBuilder = Widget Function(BuildContext context, NexusSurveyController controller, NexusSurveyQuestion question)

Override the rendering of a single question. Return your own widget; read the current value with controller.answerFor(question.id) and write it with controller.setAnswer(...) / controller.toggleChoice(...).

NexusSurveyViewCopy Anchor Link

class NexusSurveyView extends StatefulWidget

The built-in survey card. Renders one question at a time with progress, a thank-you screen, and default widgets per question type. Pass a questionBuilder to override individual questions, or replace the whole card via NexusSurveyOverlay(surveyBuilder: ...).

NexusSurveyViewCopy Anchor Link

const NexusSurveyView({super.key, required this.controller, this.questionBuilder})

Parameters

controllerCopy Anchor Link

final NexusSurveyController controller

questionBuilderCopy Anchor Link

final NexusQuestionBuilder? questionBuilder

NexusSurveyBuilderCopy Anchor Link

typedef NexusSurveyBuilder = Widget Function(BuildContext context, NexusSurveyController controller)

Fully replace the survey UI. You receive the NexusSurveyController; render whatever you want and drive it (answers, next/back, complete, dismiss, close).

NexusSurveyOverlayCopy Anchor Link

class NexusSurveyOverlay extends StatefulWidget

Hosts the currently-active survey above your app. Add it via MaterialApp.builder so it has a Material/Overlay/MediaQuery ancestor:

MaterialApp(
  builder: (context, child) => NexusSurveyOverlay(child: child!),
  // ...
)

Bring your own UI with surveyBuilder (whole card) or questionBuilder (per question) — otherwise the built-in NexusSurveyView is used.

NexusSurveyOverlayCopy Anchor Link

const NexusSurveyOverlay({super.key, required this.child, this.surveyBuilder, this.questionBuilder})

Parameters

childCopy Anchor Link

final Widget child

surveyBuilderCopy Anchor Link

final NexusSurveyBuilder? surveyBuilder

questionBuilderCopy Anchor Link

final NexusQuestionBuilder? questionBuilder