Configure

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

Full schema

interface InsitoConfig {
  apiKey: string;                     // Required
  apiUrl?: string;                    // default: https://api.insito.app
  requestTimeoutMs?: number;          // default: 5000
  debug?: boolean;                    // default: false
  environment?: "production" | "staging" | "development";
  deferCollection?: boolean;          // default: false — wait for optIn()
  theme?: {
    preset?: "light" | "dark" | "minimal" | "rounded";
    overrides?: Partial<InsitoTheme>;
  };
  labels?: Partial<SdkLabels>;        // override built-in UI text
  events?: { name: string; description?: string }[];   // declare trigger events
  screens?: { name: string; description?: string }[];  // declare screens
}

`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: put it in .env (for example EXPO_PUBLIC_INSITO_API_KEY) and read it via expo-constants or react-native-config, so you can regenerate it without a code change.

import Constants from "expo-constants";

MicroSurvey.init({
  apiKey: Constants.expoConfig.extra.insitoApiKey,
});

`apiUrl`

Defaults to https://api.insito.app. Must be https://: from 0.2.4, init() throws 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 __DEV__ build. Override when:

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

MicroSurvey.init({
  apiKey: "proj_xxx",
  apiUrl: __DEV__ ? "http://localhost:3001" : undefined,
});

Local dev with iOS Simulator: use the host machine’s LAN IP (http://192.168.x.x:3001), not localhost. The simulator treats localhost as itself.

`requestTimeoutMs`

How long the SDK waits for any one request before giving up. Defaults to 5,000 ms (5 seconds). Lower this if your users are on consistently fast networks and you want triggers to fail fast. Raise it if you have a lot of users 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. `response_submitted` 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. `response_failed` 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

The queue lives in AsyncStorage, which Android Auto Backup copies to the user’s Google Drive by default. To keep queued answers on the device, exclude the AsyncStorage database in android/app/src/main/res/xml/:

data_extraction_rules.xml (Android 12+)

<data-extraction-rules>
  <cloud-backup>
    <exclude domain="database" path="RKStorage" />
    <exclude domain="database" path="RKStorage-journal" />
  </cloud-backup>
  <device-transfer>
    <exclude domain="database" path="RKStorage" />
    <exclude domain="database" path="RKStorage-journal" />
  </device-transfer>
</data-extraction-rules>

backup_rules.xml (Android 11 and lower)

<full-backup-content>
  <exclude domain="database" path="RKStorage" />
  <exclude domain="database" path="RKStorage-journal" />
</full-backup-content>

Then reference both from the <application> tag in AndroidManifest.xml:

<application
  android:dataExtractionRules="@xml/data_extraction_rules"
  android:fullBackupContent="@xml/backup_rules"
  ...>

This excludes all of your app’s AsyncStorage data from backups, not just Insito’s. In an Expo project without a custom config plugin, set "android": { "allowBackup": false } in app.json to switch backups off entirely.

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

MicroSurvey.init({ apiKey: "proj_xxx", deferCollection: true });

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

`debug`

Enables console.log output for SDK internals — init, identify, trigger, queue flushes, screen-map flushes, plus error details. Recommended:

MicroSurvey.init({
  apiKey: "proj_xxx",
  debug: __DEV__,
});

Off by default so production 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:

MicroSurvey.init({
  apiKey: "proj_xxx",
  environment: __DEV__ ? "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 `expo-localization` if installed, else `Intl`.
`timezone`	`America/New_York`	IANA timezone from `Intl`.
`osVersion`	`17.2`	The OS version string.
`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 }).

locale resolution prefers the optional expo-localization peer dependency and falls back to the built-in Intl API, so it works in both Expo and bare React Native apps without any extra setup.

`theme`

Pick a preset, override individual tokens, or both. See Theming for the full token list.

MicroSurvey.init({
  apiKey: "proj_xxx",
  theme: {
    preset: "rounded",
    overrides: {
      colors: {
        primary: "#FF6B35",
      },
    },
  },
});

Updating config after init

init() is a one-shot — repeat calls are ignored, so the theme preset and token overrides are fixed for the session. <InsitoProvider> has no theme prop. What you can change at runtime is the light/dark appearance (for Brand Kit surveys set to themeMode: "auto"), via the provider’s appearance prop:

<InsitoProvider appearance={darkMode ? "dark" : "light"}>
  <App />
</InsitoProvider>

appearance defaults to "system" (follow the device). See Theming.

`labels`

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

MicroSurvey.init({
  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.

MicroSurvey.init({
  apiKey: "proj_xxx",
  events: [
    { name: "checkout_completed", description: "User finished a purchase" },
    { name: "transfer_sent" },
  ],
  screens: [{ 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.

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

`theme`

Updating config after init

`labels`

`events` and `screens`

Full schema

apiKey (required)

apiUrl

requestTimeoutMs

Offline delivery

Android backups

deferCollection

debug

environment

Auto-captured device metadata

theme

Updating config after init

labels

events and screens

`apiKey` (required)

`apiUrl`

`requestTimeoutMs`

`deferCollection`

`debug`

`environment`

`theme`

`labels`

`events` and `screens`