Configure

MicroSurvey.init(config) takes a single InsitoConfig. Most apps need just apiKey — every other field is optional with a sane default.

Full schema

class InsitoConfig {
  const InsitoConfig({
    required this.apiKey,                 // Required
    this.apiUrl,                          // default: https://api.insito.app
    this.requestTimeoutMs,                // default: 5000
    this.debug = false,                   // default: false
    this.environment,                     // 'production' | 'staging' | 'development'
    this.deferCollection = false,         // wait for MicroSurvey.optIn()
    this.themePreset = ThemePreset.light, // survey modal preset
    this.themeOverrides,                  // InsitoThemeOverrides — deep-merged
    this.labels,                          // Map<String, String> — override UI text
    this.events,                          // List<InsitoVariableDeclaration>
    this.screens,                         // List<InsitoVariableDeclaration>
  });
}

`apiKey` (required)

Your project key. Format proj_xxx. Get it from the dashboard → your app → Settings → Mobile SDK.

The project key is public, not a secret: it ships inside your app. Abuse is bounded by per-key rate limits and your plan’s response quota. Keep it out of public repos anyway: pass it in at build time with --dart-define and read it via String.fromEnvironment('INSITO_API_KEY'), so you can regenerate it without a code change.

await MicroSurvey.init(
  const InsitoConfig(
    apiKey: String.fromEnvironment('INSITO_API_KEY'),
  ),
);

`apiUrl`

Defaults to https://api.insito.app. Must be https://: from 0.2.4, init() throws an ArgumentError on an http:// URL unless it points at localhost, 127.0.0.1, 10.0.2.2 or a private-network IP and the build is a debug build (kDebugMode). Override when:

Pointing the SDK at a staging environment.
Running against a local API instance during development.

await MicroSurvey.init(
  InsitoConfig(
    apiKey: 'proj_xxx',
    apiUrl: kDebugMode ? 'http://localhost:3001' : null,
  ),
);

Local dev with the iOS Simulator: use your host machine’s LAN IP (http://192.168.x.x:3001), not localhost. On the Android emulator, use http://10.0.2.2:3001 to reach the host.

`requestTimeoutMs`

How long the SDK waits for any one request before giving up. Defaults to 5,000 ms (5 seconds). Lower it on consistently fast networks to fail fast; raise it if a lot of users are on weak cellular — too-tight timeouts increase the offline-queue backlog.

Offline delivery

submitResponse never loses answers to a flaky network. Each answer set gets an Idempotency-Key that’s reused on every retry, so the server records it once however many times it’s sent.

Server answer	What the SDK does
`2xx` (including a replay)	Delivered. `responseSubmitted` fires.
Offline, timeout, `408`, `429`, `5xx`	Queued. Retried with exponential backoff (2 s up to 5 min, with jitter, never sooner than `Retry-After`) and whenever the app returns to the foreground.
`401`, `402`	Queued, but not retried on a timer. Tried again on the next foreground or launch, in case the key or plan has been fixed.
Other `4xx`	Dropped. `responseFailed` fires with the server’s error code.

The queue holds up to 200 answer sets for up to 7 days; older items are discarded unsent.

Android backups

On Android the queue is stored in the app’s no_backup directory, which Auto Backup and device-to-device transfer never copy. A queue left in SharedPreferences by an SDK version before 0.2.4 is moved there on first use. On iOS it stays in NSUserDefaults (through shared_preferences).

`deferCollection`

Set deferCollection: true when your app asks for consent before collecting feedback. The SDK then sends nothing (no identify, triggers, screen tracking or responses) until you call MicroSurvey.optIn(). The decision is stored on the device, so optIn() only needs to be called once, and MicroSurvey.optOut() stops collection again. Requires 0.3.0+. See Privacy and data requests.

await MicroSurvey.init(const InsitoConfig(apiKey: 'proj_xxx', deferCollection: true));

// After the user accepts:
await MicroSurvey.optIn();
await MicroSurvey.identify(UserProperties(userId: user.id));

`debug`

Enables debugPrint output for SDK internals — init, identify, trigger, queue flushes, screen-map flushes, plus error details. Off by default so release builds stay quiet.

import 'package:flutter/foundation.dart'; // kDebugMode

await MicroSurvey.init(
  InsitoConfig(apiKey: 'proj_xxx', debug: kDebugMode),
);

`environment`

Tags every respondent with the app environment so you can keep staging and development traffic out of your audience targeting and analytics. There’s no way to detect this automatically, so you opt in:

await MicroSurvey.init(
  InsitoConfig(
    apiKey: 'proj_xxx',
    environment: kDebugMode ? 'development' : 'production',
  ),
);

It’s forwarded as environment alongside the auto-captured device metadata (see below) and is available as a Device property in the survey Audience filter builder.

Auto-captured device metadata

On every identify() the SDK automatically captures a small set of device + lifecycle properties — no extra code required:

Property	Example	Notes
`locale`	`en-US`	From `PlatformDispatcher.instance.locale`.
`timezone`	`CET`	From `DateTime.now().timeZoneName`.
`osVersion`	`Version 17.2 (Build ...)`	From `Platform.operatingSystemVersion`.
`sessionCount`	`14`	Times the app has launched (persisted locally).
`daysSinceInstall`	`30`	Whole days since the first `init()`.

These land in the respondent’s metadata and show up as Device properties in the Audience filter builder. Anything you pass in identify(metadata: ...) wins over an auto-captured key of the same name. For fully custom, business-level properties (like plan or transactionsThisMonth) use identify(properties: ...).

`themePreset` and `themeOverrides`

Pick one of the four built-in presets and, optionally, deep-merge individual token overrides on top. See Theming for the full token list.

await MicroSurvey.init(
  const InsitoConfig(
    apiKey: 'proj_xxx',
    themePreset: ThemePreset.rounded,
    themeOverrides: InsitoThemeOverrides(
      colors: InsitoColorsOverride(primary: Color(0xFFFF6B35)),
    ),
  ),
);

`labels`

Override the SDK’s built-in UI text (buttons, placeholders, NPS anchors, the progress counter) as a Map<String, String>. Most teams set these from the dashboard instead; use this when code should win. See Labels.

await MicroSurvey.init(
  const InsitoConfig(
    apiKey: 'proj_xxx',
    labels: {'next': 'Continue', 'submit': 'Send'},
  ),
);

`events` and `screens`

Declare the events and screens this app can trigger surveys on. They’re registered in the dashboard’s App Variable Registry on the next identify() call, so teammates can pick them from a searchable list when configuring a survey’s trigger — even before the SDK has fired them once.

await MicroSurvey.init(
  const InsitoConfig(
    apiKey: 'proj_xxx',
    events: [
      InsitoVariableDeclaration(
        name: 'checkout_completed',
        description: 'User finished a purchase',
      ),
      InsitoVariableDeclaration(name: 'transfer_sent'),
    ],
    screens: [
      InsitoVariableDeclaration(name: '/checkout', description: 'The checkout screen'),
    ],
  ),
);

name must match exactly what your app passes to trigger() (for events) or reports as the screen name. Declared variables show as Not seen yet in the dashboard until the SDK actually fires them, at which point they flip to Verified. Auto-discovered events/screens appear automatically — you only need to declare the ones you want available up front.

The declarations are sent on the next identify() and re-sent whenever the list changes, so editing them ships with your next release.

Updating config after init

init() is a one-shot — repeat calls are ignored. To change the light/dark scheme mid-session, use the appearance prop on InsitoProvider instead of re-initialising.

Get started

Concepts

Privacy and compliance

React Native SDK

Flutter SDK

Dashboard

MCP server

Full schema

`apiKey` (required)

`apiUrl`

`requestTimeoutMs`

Offline delivery

Android backups

`deferCollection`

`debug`

`environment`

Auto-captured device metadata

`themePreset` and `themeOverrides`

`labels`

`events` and `screens`

Updating config after init

Full schema

apiKey (required)

apiUrl

requestTimeoutMs

Offline delivery

Android backups

deferCollection

debug

environment

Auto-captured device metadata

themePreset and themeOverrides

labels

events and screens

Updating config after init

`apiKey` (required)

`apiUrl`

`requestTimeoutMs`

`deferCollection`

`debug`

`environment`

`themePreset` and `themeOverrides`

`labels`

`events` and `screens`