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";
  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 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. For local development, drop it in .env and import via expo-constants or react-native-config.

import Constants from "expo-constants";

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

`apiUrl`

Defaults to https://api.insito.app. 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.

`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

React Native SDK

Flutter SDK

Dashboard

MCP server

Full schema

`apiKey` (required)

`apiUrl`

`requestTimeoutMs`

`debug`

`environment`

Auto-captured device metadata

`theme`

Updating config after init

`labels`

`events` and `screens`

​Full schema

​apiKey (required)

​apiUrl

​requestTimeoutMs

​debug

​environment

​Auto-captured device metadata

​theme

​Updating config after init

​labels

​events and screens

Full schema

`apiKey` (required)

`apiUrl`

`requestTimeoutMs`

`debug`

`environment`

Auto-captured device metadata

`theme`

Updating config after init

`labels`

`events` and `screens`