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

Full schema

apiKey (required)

Your project secret. Format proj_xxx. Get it from the dashboard → your project → Settings → API key.
The API key is a secret. Don’t commit it to a public repo. Pass it in at build time with --dart-define and read it via String.fromEnvironment('INSITO_API_KEY').

apiUrl

Defaults to https://api.insito.app. Override when:
  • Pointing the SDK at a staging environment.
  • Running against a local API instance during development.
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.

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.

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

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.

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