API reference

The package has a tiny surface — one facade (MicroSurvey), one widget (InsitoProvider), and one navigator observer (InsitoNavigatorObserver). Everything else is a type or theme helper.

Import

import 'package:insito_flutter/insito_flutter.dart';

That single barrel export covers MicroSurvey, InsitoConfig, UserProperties, InsitoProvider, InsitoAppearance, InsitoNavigatorObserver, the InsitoEvent enum + InsitoEventPayload, the theme types (ThemePreset, InsitoTheme, InsitoThemeOverrides, …, resolveTheme, themePresets), BrandConfig, and the survey types (ActiveSurvey, Answer, SurveyQuestion, QuestionType, SdkState, …).

`MicroSurvey`

A static facade over the SDK singleton. Holds the state machine and the imperative methods you call from your app.

`MicroSurvey.init(config)` → `Future<void>`

Boots the SDK. Call once, as early as possible (top of main() after WidgetsFlutterBinding.ensureInitialized()). Subsequent calls are ignored with a debug warning.

String

required

Project API key. Format: proj_xxx. Throws if malformed.

String?

default:"https://api.insito.app"

Override the API base URL — useful for staging or self-hosted instances.

int?

default:"5000"

Per-request timeout in milliseconds. Lowering this on flaky networks routes more responses through the offline queue.

bool

default:"false"

Toggles internal debugPrint output. Recommended: debug: kDebugMode.

String?

production / staging / development. Forwarded as respondent metadata for audience filtering.

bool

default:"false"

Send nothing until MicroSurvey.optIn() is called, for apps that ask for consent first. The decision is stored on the device. See Consent.

ThemePreset

default:"ThemePreset.light"

Base preset for the survey modal. See Theming.

InsitoThemeOverrides?

Partial token overrides deep-merged on top of the preset (and any Brand Kit).

Map<String, String>?

Override built-in UI chrome strings. See Labels.

List<InsitoVariableDeclaration>?

Declare trigger events for the dashboard registry. See Configure.

List<InsitoVariableDeclaration>?

Declare screens for the dashboard registry.

`MicroSurvey.identify(user)` → `Future<void>`

Associates subsequent triggers with a stable user. Cached for 24 hours per userId, so repeat calls don’t hit the network. Takes a UserProperties:

String

required

Stable, unique identifier for your user, such as the user’s ID in your database. Don’t pass an email address, phone number or name: an opaque ID keeps answers pseudonymous. See Privacy.

String?

e.g. "ios", "android". Used by analytics for platform breakdowns.

String?

Your app’s build version, e.g. "2.7.0". Surfaces in the dashboard so you can correlate feedback with releases.

Map<String, dynamic>?

Free-form device-level key/value pairs. Merged on top of the SDK’s auto-captured device metadata — your keys win on a collision.

Map<String, Object>?

Custom, business-level user properties (e.g. plan: "premium", transactionsThisMonth: 14). Discovered into the dashboard User Properties registry as type-aware audience filters. Only String / num / bool values are kept. Call identify() again whenever a value changes — the API always uses the most recent value.

await MicroSurvey.identify(
  const UserProperties(
    userId: 'auth_4f93k',
    platform: 'ios',
    appVersion: '2.7.0',
    metadata: {'cohort': 'beta-q2'},
    properties: {'plan': 'premium', 'transactionsThisMonth': 14},
  ),
);

`MicroSurvey.trigger(eventName)` → `Future<void>`

Fires a trigger by name. The server decides whether to show a survey; if so, the modal renders inside InsitoProvider.

String

required

Lowercase snake_case event name configured against a survey in the dashboard (e.g. "checkout_completed"). See Triggers.

MicroSurvey.trigger('checkout_completed');

Guards (all fire-and-forget, errors swallowed):

Not initialised → no-op + debug warning.
No identify() call yet → no-op + debug warning.
A survey is already active → no-op + debug log.

`MicroSurvey.evaluate([reason, options])` → `Future<void>`

Re-checks the auto-evaluated trigger types for the current user (e.g. session count / days-since-install rules) without a specific event name.

`MicroSurvey.submitResponse(surveyId, answers, [options])` → `Future<SubmitResponseResult>`

Used internally by the built-in modal. Call it directly only if you’re rendering your own question UI.

String

required

The active survey’s ID — usually MicroSurvey.activeSurvey?.surveyId.

List<Answer>

required

List of Answer(questionId, type, value). See Answer below.

The result’s status is SubmitStatus.success, queued or failed. queued means the answers are saved on the device and will be delivered later (see Offline delivery).

`MicroSurvey.savePartialProgress(surveyId, answers, [existingResponseId])` → `Future<String?>`

Persists partial answers (autosave) mid-survey, returning the response ID so subsequent saves update the same row.

`MicroSurvey.dismissSurvey()` → `void`

Closes the active modal without submitting. Emits surveyDismissed. Used by the built-in close button.

`MicroSurvey.on(event, listener)` / `MicroSurvey.off(event, listener)`

Subscribe to lifecycle events. on() returns an unsubscribe function.

final off = MicroSurvey.on(InsitoEvent.responseSubmitted, (p) {
  analytics.track('survey_response_submitted', {'surveyId': p.surveyId});
});
// later
off();

See Lifecycle events for the full event matrix. Requires 0.3.0+. See Privacy and data requests.

MicroSurvey.optOut() → Future<void> stops all collection on this device until optIn(): no identify, triggers, screen tracking or responses. Queued responses and the cached identity are deleted, and an open survey closes. The decision is stored, and it can be called before init().
MicroSurvey.optIn() → Future<void> allows collection again, or for the first time with deferCollection. Call identify() afterwards.
MicroSurvey.reset() → Future<void> forgets the identified user, for example on logout. Queued answers are still delivered and the consent decision is kept.
MicroSurvey.consent → ConsentState: granted, denied, or pending (with deferCollection before optIn()).

While collection is disabled, submitResponse() returns SubmitStatus.failed with reason collection_disabled and stores nothing.

// In your consent screen:
if (accepted) {
  await MicroSurvey.optIn();
  await MicroSurvey.identify(UserProperties(userId: user.id));
} else {
  await MicroSurvey.optOut();
}

`MicroSurvey.recordScreenVisit(name)` → `void`

Records a screen visit and fires screen_viewed:<name> when a user is identified. InsitoNavigatorObserver calls this for you; use it directly for routing that isn’t Navigator-driven. See Screen tracking.

Read-only state

MicroSurvey.state         // SdkState: idle | loading | surveyActive | completed
MicroSurvey.activeSurvey  // ActiveSurvey?
MicroSurvey.user          // InsitoUser?
MicroSurvey.consent       // ConsentState: granted | denied | pending

Widgets

`InsitoProvider`

Renders the survey modal above your app. Wrap it around your MaterialApp.

Widget

required

Your app (typically a MaterialApp).

InsitoAppearance

default:"InsitoAppearance.system"

Drives the light/dark scheme for themeMode: "auto" surveys. system follows the device; light / dark mirror your app’s own theme. See Theming.

InsitoProvider(
  appearance: InsitoAppearance.system,
  child: MaterialApp(home: const HomeScreen()),
);

`InsitoNavigatorObserver`

A NavigatorObserver that reports screen visits. Add it to MaterialApp(navigatorObservers: [InsitoNavigatorObserver()]). See Screen tracking.

Theme helpers

`resolveTheme(preset, [overrides])` → `InsitoTheme`

Builds a fully-populated InsitoTheme from a ThemePreset plus optional InsitoThemeOverrides. Useful for previewing a theme outside the SDK.

`themePresets`

The raw preset map: Map<ThemePreset, InsitoTheme>. Each entry is a complete InsitoTheme.

Types

`Answer`

class Answer {
  final String questionId;
  final QuestionType type; // nps | rating | multipleChoice | openText
  final Object value;      // int, String, or List<String>
}

nps: value is an int 0–10.
rating: value is an int 1–5.
multipleChoice: value is a String (single-select) or List<String> (multi-select).
openText: value is a String.

`SdkState`

enum SdkState { idle, loading, surveyActive, completed }

idle → user can fire trigger().
loading → trigger in flight to the server.
surveyActive → modal is on screen.
completed → response submitted, modal closed (transient).

`QuestionType`

enum QuestionType { nps, rating, multipleChoice, openText, welcomeScreen, endScreen }

The four answerable types collect a response; welcomeScreen / endScreen are copy/CTA-only steps. Each maps to a wire value (nps, rating, multiple_choice, open_text, welcome_screen, end_screen).

`InsitoEvent`

enum InsitoEvent {
  initialized,
  surveyShown,
  surveyDismissed,
  surveyCompleted,
  responseSubmitted,
  responseQueued,
  responseFailed,
  screenTracked,
  screenMapFlushed,
  error,
}

See Lifecycle events for the payload of each.

Get started

Concepts

Privacy and compliance

React Native SDK

Flutter SDK

Dashboard

MCP server

Import

`MicroSurvey`

`MicroSurvey.init(config)` → `Future<void>`

`MicroSurvey.identify(user)` → `Future<void>`

`MicroSurvey.trigger(eventName)` → `Future<void>`

`MicroSurvey.evaluate([reason, options])` → `Future<void>`

`MicroSurvey.submitResponse(surveyId, answers, [options])` → `Future<SubmitResponseResult>`

`MicroSurvey.savePartialProgress(surveyId, answers, [existingResponseId])` → `Future<String?>`

`MicroSurvey.dismissSurvey()` → `void`

`MicroSurvey.on(event, listener)` / `MicroSurvey.off(event, listener)`

`MicroSurvey.recordScreenVisit(name)` → `void`

Read-only state

Widgets

`InsitoProvider`

`InsitoNavigatorObserver`

Theme helpers

`resolveTheme(preset, [overrides])` → `InsitoTheme`

`themePresets`

Types

`Answer`

`SdkState`

`QuestionType`

`InsitoEvent`

Import

MicroSurvey

MicroSurvey.init(config) → Future<void>

MicroSurvey.identify(user) → Future<void>

MicroSurvey.trigger(eventName) → Future<void>

MicroSurvey.evaluate([reason, options]) → Future<void>

MicroSurvey.submitResponse(surveyId, answers, [options]) → Future<SubmitResponseResult>

MicroSurvey.savePartialProgress(surveyId, answers, [existingResponseId]) → Future<String?>

MicroSurvey.dismissSurvey() → void

MicroSurvey.on(event, listener) / MicroSurvey.off(event, listener)

Consent and data

MicroSurvey.recordScreenVisit(name) → void

Read-only state

Widgets

InsitoProvider

InsitoNavigatorObserver

Theme helpers

resolveTheme(preset, [overrides]) → InsitoTheme

themePresets

Types

Answer

SdkState

QuestionType

InsitoEvent

`MicroSurvey`

`MicroSurvey.init(config)` → `Future<void>`

`MicroSurvey.identify(user)` → `Future<void>`

`MicroSurvey.trigger(eventName)` → `Future<void>`

`MicroSurvey.evaluate([reason, options])` → `Future<void>`

`MicroSurvey.submitResponse(surveyId, answers, [options])` → `Future<SubmitResponseResult>`

`MicroSurvey.savePartialProgress(surveyId, answers, [existingResponseId])` → `Future<String?>`

`MicroSurvey.dismissSurvey()` → `void`

`MicroSurvey.on(event, listener)` / `MicroSurvey.off(event, listener)`

`MicroSurvey.recordScreenVisit(name)` → `void`

`InsitoProvider`

`InsitoNavigatorObserver`

`resolveTheme(preset, [overrides])` → `InsitoTheme`

`themePresets`

`Answer`

`SdkState`

`QuestionType`

`InsitoEvent`