> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insito.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Every method, type, and lifecycle event exported by the insito_flutter package.

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

```dart theme={null}
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.

<ParamField path="config.apiKey" type="String" required>
  Project API key. Format: `proj_xxx`. Throws if malformed.
</ParamField>

<ParamField path="config.apiUrl" type="String?" default="https://api.insito.app">
  Override the API base URL — useful for staging or self-hosted instances.
</ParamField>

<ParamField path="config.requestTimeoutMs" type="int?" default="5000">
  Per-request timeout in milliseconds. Lowering this on flaky networks routes
  more responses through the offline queue.
</ParamField>

<ParamField path="config.debug" type="bool" default="false">
  Toggles internal `debugPrint` output. Recommended: `debug: kDebugMode`.
</ParamField>

<ParamField path="config.environment" type="String?">
  `production` / `staging` / `development`. Forwarded as respondent metadata for
  audience filtering.
</ParamField>

<ParamField path="config.themePreset" type="ThemePreset" default="ThemePreset.light">
  Base preset for the survey modal. See [Theming](/sdk/flutter/theming).
</ParamField>

<ParamField path="config.themeOverrides" type="InsitoThemeOverrides?">
  Partial token overrides deep-merged on top of the preset (and any Brand Kit).
</ParamField>

<ParamField path="config.labels" type="Map<String, String>?">
  Override built-in UI chrome strings. See [Labels](/sdk/flutter/labels).
</ParamField>

<ParamField path="config.events" type="List<InsitoVariableDeclaration>?">
  Declare trigger events for the dashboard registry. See
  [Configure](/sdk/flutter/configure#events-and-screens).
</ParamField>

<ParamField path="config.screens" type="List<InsitoVariableDeclaration>?">
  Declare screens for the dashboard registry.
</ParamField>

### `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`:

<ParamField path="user.userId" type="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.
</ParamField>

<ParamField path="user.platform" type="String?">
  e.g. `"ios"`, `"android"`. Used by analytics for platform breakdowns.
</ParamField>

<ParamField path="user.appVersion" type="String?">
  Your app's build version, e.g. `"2.7.0"`. Surfaces in the dashboard so you can
  correlate feedback with releases.
</ParamField>

<ParamField path="user.metadata" type="Map<String, dynamic>?">
  Free-form device-level key/value pairs. Merged on top of the SDK's
  [auto-captured device metadata](/sdk/flutter/configure#auto-captured-device-metadata)
  — your keys win on a collision.
</ParamField>

<ParamField path="user.properties" type="Map<String, Object>?">
  Custom, business-level user properties (e.g. `plan: "premium"`,
  `transactionsThisMonth: 14`). Discovered into the dashboard
  [User Properties](/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.
</ParamField>

```dart theme={null}
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`.

<ParamField path="eventName" type="String" required>
  Lowercase snake\_case event name configured against a survey in the dashboard
  (e.g. `"checkout_completed"`). See [Triggers](/concepts/triggers).
</ParamField>

```dart theme={null}
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.

<ParamField path="surveyId" type="String" required>
  The active survey's ID — usually `MicroSurvey.activeSurvey?.surveyId`.
</ParamField>

<ParamField path="answers" type="List<Answer>" required>
  List of `Answer(questionId, type, value)`. See [Answer](#answer) below.
</ParamField>

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

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

See [Lifecycle events](/sdk/flutter/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](/sdk/flutter/screen-tracking).

### Read-only state

```dart theme={null}
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`.

<ParamField path="child" type="Widget" required>
  Your app (typically a `MaterialApp`).
</ParamField>

<ParamField path="appearance" type="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](/sdk/flutter/theming#follow-your-apps-theme).
</ParamField>

```dart theme={null}
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](/sdk/flutter/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`

```dart theme={null}
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`

```dart theme={null}
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`

```dart theme={null}
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`

```dart theme={null}
enum InsitoEvent {
  initialized,
  surveyShown,
  surveyDismissed,
  surveyCompleted,
  responseSubmitted,
  responseQueued,
  responseFailed,
  screenTracked,
  screenMapFlushed,
  error,
}
```

See [Lifecycle events](/sdk/flutter/events) for the payload of each.