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.

config.apiKey

String

required

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

config.apiUrl

String?

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

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

config.requestTimeoutMs

int?

default:"5000"

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

config.debug

bool

default:"false"

Toggles internal debugPrint output. Recommended: debug: kDebugMode.

config.environment

String?

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

config.themePreset

ThemePreset

default:"ThemePreset.light"

Base preset for the survey modal. See Theming.

config.themeOverrides

InsitoThemeOverrides?

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

config.labels

Map<String, String>?

Override built-in UI chrome strings. See Labels.

config.events

List<InsitoVariableDeclaration>?

Declare trigger events for the dashboard registry. See Configure.

config.screens

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:

user.userId

String

required

Stable, unique identifier for your user. Most teams pass their database user ID. Do NOT pass an email or anything PII unless you’ve configured PII handling on your account.

user.platform

String?

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

user.appVersion

String?

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

user.metadata

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.

user.properties

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.

eventName

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.

surveyId

String

required

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

answers

List<Answer>

required

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

`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.

`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?

Widgets

`InsitoProvider`

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

child

Widget

required

Your app (typically a MaterialApp).

appearance

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

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)

​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)`

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

Read-only state

Widgets

`InsitoProvider`

`InsitoNavigatorObserver`

Theme helpers

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

`themePresets`

Types

`Answer`

`SdkState`

`QuestionType`

`InsitoEvent`