API reference

The package has a small surface — one singleton (MicroSurvey), one React provider (<InsitoProvider>), one hook (useInsito), and one navigation helper (useInsitoScreenTracking), plus theme/label helpers.

Imports

import {
  MicroSurvey,
  InsitoProvider,
  useInsito,
  useInsitoScreenTracking,
  resolveTheme,
  themePresets,
  SDK_DEFAULT_LABELS,
  resolveLabels,
} from "@insito/react-native";

import type {
  InsitoConfig,
  InsitoVariableDeclaration,
  InsitoTheme,
  IdentifyArgs,
  InsitoEvent,
  InsitoEventName,
  InsitoEventListener,
  ActiveSurvey,
  Answer,
  SurveyQuestion,
  SdkState,
  SdkLabels,
  ThemePreset,
  InsitoUser,
  ApiResponse,
  InsitoProviderProps,
  InsitoAppearance,
  SubmitResponseOptions,
  SubmitResponseResult,
} from "@insito/react-native";

`MicroSurvey`

The named-export singleton (import { MicroSurvey }). Holds the SDK state machine and the imperative methods you call from your app.

`MicroSurvey.init(config)`

Boots the SDK. Call once, as early as possible (module top-level is fine). Subsequent calls are silently ignored; a console warning is emitted only when debug: true was set on the first successful init().

config.apiKey

string

required

Project API key. Format: proj_xxx. Throws synchronously if malformed.

config.apiUrl

string

default:"https://api.insito.app"

Override the API base URL — useful for staging environments or self-hosted instances. Default points to production.

config.requestTimeoutMs

number

default:"5000"

Per-request timeout in milliseconds. Lowering this on flaky networks will route more responses through the offline queue.

config.debug

boolean

default:"false"

Toggles internal console.log output. Recommended: debug: __DEV__.

config.environment

string

Optional environment tag (e.g. "production", "staging") sent as device metadata and usable in audience filters.

config.theme

object

{ preset?: 'light' | 'dark' | 'minimal' | 'rounded', overrides?: Partial<InsitoTheme> }. See Theming.

config.labels

Partial<SdkLabels>

In-code overrides for the built-in UI strings. See Labels.

config.events

InsitoVariableDeclaration[]

Event keys to pre-declare into the registry on the next identify().

config.screens

InsitoVariableDeclaration[]

Screen names to pre-declare into the registry on the next identify().

MicroSurvey.init({
  apiKey: "proj_xxx",
  debug: __DEV__,
  environment: "production",
  theme: { preset: "rounded" },
});

`MicroSurvey.identify(args)`

Associates subsequent triggers with a stable user. Cached for 24 hours per userId so repeat calls don’t hit the network.

args.userId

string

required

Stable, unique identifier for your user. Most teams pass their database user ID. Do NOT pass an email or anything PII unless you’ve configured PII handling on your account.

args.platform

string

e.g. "ios", "android", "web". Used by analytics for platform breakdowns.

args.appVersion

string

Your app’s build version, e.g. "2.7.0". Surfaces in the dashboard so you can correlate feedback with releases.

args.metadata

Record<string, unknown>

Free-form device-level key/value pairs. Merged on top of the SDK’s auto-captured device metadata — your keys win on a collision.

args.properties

Record<string, string | number | boolean>

Custom, business-level user properties (e.g. plan: "premium", transactionsThisMonth: 14, hasLinkedCard: true). Stored on the respondent and discovered into the dashboard User Properties registry, where they become type-aware audience filters. Only string / number / boolean values are kept. Call identify() again whenever a value changes — the API always uses the most recent value.

await MicroSurvey.identify({
  userId: "auth_4f93k...",
  platform: "ios",
  appVersion: "2.7.0",
  metadata: { cohort: "beta-q2" },
  properties: {
    plan: "premium",
    transactionsThisMonth: 14,
    hasLinkedCard: true,
  },
});

Even with no metadata or properties, every identify() auto-captures device + lifecycle metadata (locale, timezone, osVersion, sessionCount, daysSinceInstall). See Configure.

`MicroSurvey.trigger(eventName)`

Fires a trigger by name. The server decides whether to show a survey. trigger() is async (Promise<void>) and sets the state to loading while the request is in flight; the modal appears once the server responds. Fire it fire-and-forget with void.

eventName

string

required

Event name configured against a survey in the dashboard (e.g. "checkout_completed"). Allowed characters are A–Z a–z 0–9 _; keys are case-sensitive. See Triggers.

void MicroSurvey.trigger("checkout_completed");

Guards:

Not initialised → no-op + debug warning.
No identify() call yet → no-op + debug warning.
A survey is already active → no-op + debug log.

`MicroSurvey.submitResponse(surveyId, answers, options?)`

Used internally by the built-in modal. You’d only call this directly if you’re rendering your own question UI.

surveyId

string

required

The active survey’s ID — usually MicroSurvey.activeSurvey?.surveyId.

answers

Answer[]

required

Array of { questionId, type, value }. See Answer type below.

options

SubmitResponseOptions

{ keepModalOpen?: boolean; responseId?: string }. Pass responseId to complete an existing partial response.

Returns Promise<SubmitResponseResult>:

type SubmitResponseResult =
  | { status: "success"; responseId: string }
  | { status: "queued" }
  | { status: "failed"; reason: string };

`MicroSurvey.evaluate(reason?, options?)`

Runs the auto-evaluated trigger check (app open, session start, screen visit). The SDK calls this automatically on identify and screen visits; call it directly only for custom lifecycle hooks. Returns Promise<void>.

`MicroSurvey.savePartialProgress(surveyId, answers, existingResponseId?)`

Persists in-progress answers for autosave-enabled surveys. Used internally by the modal as the user advances; returns the partial response id.

`MicroSurvey.dismissSurvey()`

Closes the active modal without submitting. Emits survey_dismissed. Used by the close button in the built-in UI.

`MicroSurvey.on(event, listener)` / `MicroSurvey.off(event, listener)`

Subscribe to lifecycle events. on() returns an unsubscribe function.

const off = MicroSurvey.on("response_submitted", ({ surveyId, responseId }) => {
  analytics.track("survey_response_submitted", { surveyId, responseId });
});
// later
off();

See Lifecycle events for the full event matrix.

`MicroSurvey.onNavigationStateChange(state)`

Bridges React Navigation v6/v7 state into the screen-map system. Subscribe in your NavigationContainer.onStateChange:

import { MicroSurvey } from "@insito/react-native";

<NavigationContainer onStateChange={MicroSurvey.onNavigationStateChange}>
  ...
</NavigationContainer>

Expo Router users should use useInsitoScreenTracking() instead.

Read-only state

MicroSurvey.state         // 'idle' | 'loading' | 'survey_active' | 'completed'
MicroSurvey.activeSurvey  // ActiveSurvey | null
MicroSurvey.user          // InsitoUser | null
MicroSurvey.theme         // InsitoTheme
MicroSurvey.config        // runtime API settings only, or null

MicroSurvey.config returns only the runtime API settings (apiKey, apiUrl, requestTimeoutMs, debug, environment) — not the theme, labels, events, or screens you passed to init().

React layer

`<InsitoProvider>`

Renders the survey bottom sheet. Wrap your app inside one (under a GestureHandlerRootView). Children render normally; the survey sheet mounts on top via @gorhom/bottom-sheet.

<InsitoProvider>
  <App />
</InsitoProvider>

Optional appearance prop drives the light/dark scheme for themeMode: "auto" surveys. Defaults to "system" (follow the device); pass "light" / "dark" to mirror your app’s own theme. See Theming.

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

`useInsito()`

Hook that returns reactive state: { activeSurvey, dismissSurvey, theme, sdkState, labels }. Re-renders when any of them change. Throws if called outside <InsitoProvider>.

function FeedbackButton() {
  const { sdkState } = useInsito();
  const disabled = sdkState === "loading" || sdkState === "survey_active";
  return (
    <Button
      disabled={disabled}
      onPress={() => MicroSurvey.trigger("manual_feedback")}
    />
  );
}

`useInsitoScreenTracking()`

Auto-tracks screen visits for Expo Router apps. Call it in your root layout — no arguments needed.

import { useInsitoScreenTracking } from "@insito/react-native";

export default function RootLayout() {
  useInsitoScreenTracking();
  return <Stack />;
}

See Screen tracking for the React Navigation alternative and the data model.

Theme helpers

`resolveTheme(preset, overrides?)`

Builds an InsitoTheme from a preset name ('light' | 'dark' | 'minimal' | 'rounded') plus optional overrides. Useful if you want to preview a theme outside the SDK.

`themePresets`

The raw preset map: { light, dark, minimal, rounded }. Each entry is a complete InsitoTheme. Use this if you want to start from a preset and tweak it deeply.

Types

`Answer`

interface Answer {
  questionId: string;
  type: "nps" | "rating" | "multiple_choice" | "open_text";
  value: string | number | string[];
}

nps: value is a number 0–10.
rating: value is a number 1–5.
multiple_choice: value is a string (single-select) or string[] (multi-select).
open_text: value is a string.

`SdkState`

type SdkState = "idle" | "loading" | "survey_active" | "completed";

State machine:

idle → user can fire trigger().
loading → trigger in flight to the server.
survey_active → modal is on screen.
completed → response submitted, modal closed (transient).

`InsitoEventName`

type InsitoEventName =
  | "initialized"
  | "survey_shown"
  | "survey_dismissed"
  | "survey_completed"
  | "response_submitted"
  | "response_queued"
  | "response_failed"
  | "screen_tracked"
  | "screen_map_flushed"
  | "error";

See Lifecycle events for the payload of each.

Get started

Concepts

React Native SDK

Flutter SDK

Dashboard

MCP server

Imports

`MicroSurvey`

`MicroSurvey.init(config)`

`MicroSurvey.identify(args)`

`MicroSurvey.trigger(eventName)`

`MicroSurvey.submitResponse(surveyId, answers, options?)`

`MicroSurvey.evaluate(reason?, options?)`

`MicroSurvey.savePartialProgress(surveyId, answers, existingResponseId?)`

`MicroSurvey.dismissSurvey()`

`MicroSurvey.on(event, listener)` / `MicroSurvey.off(event, listener)`

`MicroSurvey.onNavigationStateChange(state)`

Read-only state

React layer

`<InsitoProvider>`

`useInsito()`

`useInsitoScreenTracking()`

Theme helpers

`resolveTheme(preset, overrides?)`

`themePresets`

Types

`Answer`

`SdkState`

`InsitoEventName`

​Imports

​MicroSurvey

​MicroSurvey.init(config)

​MicroSurvey.identify(args)

​MicroSurvey.trigger(eventName)

​MicroSurvey.submitResponse(surveyId, answers, options?)

​MicroSurvey.evaluate(reason?, options?)

​MicroSurvey.savePartialProgress(surveyId, answers, existingResponseId?)

​MicroSurvey.dismissSurvey()

​MicroSurvey.on(event, listener) / MicroSurvey.off(event, listener)

​MicroSurvey.onNavigationStateChange(state)

​Read-only state

​React layer

​<InsitoProvider>

​useInsito()

​useInsitoScreenTracking()

​Theme helpers

​resolveTheme(preset, overrides?)

​themePresets

​Types

​Answer

​SdkState

​InsitoEventName

Imports

`MicroSurvey`

`MicroSurvey.init(config)`

`MicroSurvey.identify(args)`

`MicroSurvey.trigger(eventName)`

`MicroSurvey.submitResponse(surveyId, answers, options?)`

`MicroSurvey.evaluate(reason?, options?)`

`MicroSurvey.savePartialProgress(surveyId, answers, existingResponseId?)`

`MicroSurvey.dismissSurvey()`

`MicroSurvey.on(event, listener)` / `MicroSurvey.off(event, listener)`

`MicroSurvey.onNavigationStateChange(state)`

Read-only state

React layer

`<InsitoProvider>`

`useInsito()`

`useInsitoScreenTracking()`

Theme helpers

`resolveTheme(preset, overrides?)`

`themePresets`

Types

`Answer`

`SdkState`

`InsitoEventName`