> ## 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 field the InsitoConfig object accepts, with defaults and recommendations.

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

## Full schema

```dart theme={null}
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.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 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. Pass it in at
  build time with `--dart-define` and read it via
  `String.fromEnvironment('INSITO_API_KEY')`.
</Warning>

```dart theme={null}
await MicroSurvey.init(
  const InsitoConfig(
    apiKey: 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.

```dart theme={null}
await MicroSurvey.init(
  InsitoConfig(
    apiKey: 'proj_xxx',
    apiUrl: kDebugMode ? 'http://localhost:3001' : null,
  ),
);
```

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

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

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

```dart theme={null}
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](/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 `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](/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/flutter/api-reference).

## `themePreset` and `themeOverrides`

Pick one of the four built-in presets and, optionally, deep-merge individual
token overrides on top. See [Theming](/sdk/flutter/theming) for the full token
list.

```dart theme={null}
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](/sdk/flutter/labels).

```dart theme={null}
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](/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.

```dart theme={null}
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'),
    ],
  ),
);
```

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

## Updating config after init

`init()` is a one-shot — repeat calls are ignored. To change the light/dark
scheme mid-session, use the [`appearance`](/sdk/flutter/theming#follow-your-apps-theme)
prop on `InsitoProvider` instead of re-initialising.