API reference

The package has a tiny surface — one singleton (MicroSurvey), one React provider (<InsitoProvider>), one hook (useInsito), and one navigation helper (useInsitoScreenTracking). Everything else is a type or theme helper.

Imports

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

import type {
  InsitoConfig,
  InsitoTheme,
  IdentifyArgs,
  InsitoEvent,
  InsitoEventName,
  ActiveSurvey,
  Answer,
  SurveyQuestion,
  SdkState,
  ThemePreset,
} from "@insito/react-native";

`MicroSurvey`

The default-exported singleton. 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 ignored with a debug warning.

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

object

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

MicroSurvey.init({
  apiKey: "proj_xxx",
  debug: __DEV__,
  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 key/value pairs (e.g. plan: "pro"). Stored on the respondent and visible per-response.

await MicroSurvey.identify({
  userId: "auth_4f93k...",
  platform: "ios",
  appVersion: "2.7.0",
  metadata: { plan: "pro", cohort: "beta-q2" },
});

`MicroSurvey.trigger(eventName)`

Fires a trigger by name. The server decides whether to show a survey. Returns immediately — the modal renders inside <InsitoProvider>.

eventName

string

required

Lowercase snake_case event name configured against a survey in the dashboard (e.g. "checkout_completed"). 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)`

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.

`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        // InsitoConfig | null

React layer

`<InsitoProvider>`

Renders the survey modal. Wrap your app inside one. Children render normally; the modal mounts on top via React Native’s <Modal>.

<InsitoProvider>
  <App />
</InsitoProvider>

Optional theme prop overrides the SDK-level theme for this subtree:

<InsitoProvider theme={{ preset: "dark" }}>
  <App />
</InsitoProvider>

`useInsito()`

Hook that returns reactive state: { state, activeSurvey, user, theme }. Re-renders when any of them change.

function FeedbackButton() {
  const { state } = useInsito();
  const disabled = state === "loading" || state === "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

Dashboard

Imports

`MicroSurvey`

`MicroSurvey.init(config)`

`MicroSurvey.identify(args)`

`MicroSurvey.trigger(eventName)`

`MicroSurvey.submitResponse(surveyId, answers)`

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

Get started

Concepts

React Native SDK

Dashboard

Documentation Index

​Imports

​MicroSurvey

​MicroSurvey.init(config)

​MicroSurvey.identify(args)

​MicroSurvey.trigger(eventName)

​MicroSurvey.submitResponse(surveyId, answers)

​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)`

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