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

# Configure

> Every option the InsitoConfig object accepts, with defaults and recommendations.

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

## Full schema

```ts theme={null}
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](https://admin.insito.app) → your project →
**Settings → API key**.

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

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

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

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

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

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

```tsx theme={null}
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](/dashboard/triggers) 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](/dashboard/triggers) 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 })`](/sdk/react-native/api-reference#microsurvey-identify-args).

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

## `theme`

Pick a preset, override individual tokens, or both. See
[Theming](/sdk/react-native/theming) for the full token list.

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

```tsx theme={null}
<InsitoProvider appearance={darkMode ? "dark" : "light"}>
  <App />
</InsitoProvider>
```

`appearance` defaults to `"system"` (follow the device). See
[Theming](/sdk/react-native/theming#follow-your-apps-theme).

## `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](/sdk/react-native/labels).

```tsx theme={null}
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](/dashboard/variables) 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.

```tsx theme={null}
MicroSurvey.init({
  apiKey: "proj_xxx",
  events: [
    { name: "checkout_completed", description: "User finished a purchase" },
    { name: "transfer_sent" },
  ],
  screens: [{ name: "Checkout", description: "The checkout screen" }],
});
```

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

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