@insito/react-native

Drop-in micro-surveys for React Native and Expo apps. Powers the Insito survey runtime.

Status: 0.1.0 — public beta. Semver stays on 0.x while the API settles.

Install

npm install @insito/react-native

Then install the required peer dependencies in your host app:

npm install @react-native-async-storage/async-storage @gorhom/bottom-sheet react-native-gesture-handler react-native-reanimated

If you use a dev client, run a native rebuild after installing the native peers.

Quick start

// app/_layout.tsx (Expo Router) — order matters for gorhom
import "react-native-gesture-handler";
import "react-native-reanimated";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
import { MicroSurvey, InsitoProvider } from "@insito/react-native";

MicroSurvey.init({
  apiKey: "proj_xxx",
  debug: __DEV__,
  // Optional (INS-144) — declare the events/screens you trigger on so they
  // appear in the dashboard's App Variable Registry before they're ever fired.
  events: [{ name: "checkout_completed", description: "User finished a purchase" }],
  screens: [{ name: "Checkout" }],
});
// `platform` is auto-detected from the device (Platform.OS) — pass it only to
// override. `appVersion` is optional.
MicroSurvey.identify({ userId: "user-123", appVersion: "1.0.0" });

export default function RootLayout() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      {/* `appearance` is optional — defaults to "system" (follow the device).
          Pass "light" / "dark" to follow your app's own theme instead. */}
      <InsitoProvider>
        <SafeAreaProvider style={{ flex: 1 }}>
          <YourApp />
        </SafeAreaProvider>
      </InsitoProvider>
    </GestureHandlerRootView>
  );
}

Surveys with a Brand Kit themeMode: "auto" follow Appearance.getColorScheme() by default. If your app themes itself in JS (or pins userInterfaceStyle), pass your current appearance to <InsitoProvider appearance="light" | "dark"> so surveys match what the user sees.

// somewhere in your app
import { MicroSurvey } from "@insito/react-native";

await MicroSurvey.trigger("checkout_completed");

Public API

| Symbol | Issue | Notes | | -------------------------- | ------- | -------------------------------------------------------------- | | MicroSurvey | INS-37 | Singleton client | | MicroSurvey.init | INS-38 | Validates config, idempotent | | MicroSurvey.identify | INS-40 | 24h AsyncStorage cache | | MicroSurvey.trigger | INS-41 | Fires event, may show survey | | MicroSurvey.submitResponse | INS-48 | Posts answers (auto-queues offline) | | MicroSurvey.dismissSurvey | INS-48 | Closes modal | | MicroSurvey.on / off | INS-52 | Pub/sub for 8 lifecycle events | | MicroSurvey.onNavigationStateChange | INS-49 | React Navigation auto-tracking | | useInsitoScreenTracking | INS-50 | Expo Router auto-tracking | | <InsitoProvider> | INS-44 | Renders the survey bottom sheet (@gorhom/bottom-sheet) | | useInsito() | INS-44 | Returns { activeSurvey, dismissSurvey, theme, sdkState } | | resolveTheme | INS-43 | Deep-merge preset + overrides |

Project structure

src/
├── index.ts                       public exports
├── InsitoClient.ts                singleton class (state machine)
├── types.ts                       InsitoConfig, InsitoTheme, InsitoEvent...
├── storage.ts                     AsyncStorage helpers
├── events.ts                      pub/sub
├── queue.ts                       offline response queue
├── screenMap.ts                   accumulator + 60s flush
├── api/client.ts                  apiFetch + timeout + retry
├── methods/
│   ├── identify.ts
│   ├── trigger.ts
│   └── submitResponse.ts
├── theme/
│   ├── tokens.ts                  shared token shape
│   ├── light.ts dark.ts minimal.ts rounded.ts
│   └── resolveTheme.ts
├── react/
│   ├── InsitoProvider.tsx
│   └── useInsito.ts
├── components/
│   ├── SurveyModal.tsx
│   ├── Questions.tsx
│   └── questions/
│       ├── NpsQuestion.tsx
│       ├── RatingQuestion.tsx
│       ├── MultipleChoiceQuestion.tsx
│       └── OpenTextQuestion.tsx
└── navigation/
    ├── onNavigationStateChange.ts
    └── useInsitoScreenTracking.ts
example/                           Expo Router host app for live verification

Build

npm install
npm run typecheck   # tsc --noEmit
npm run build       # tsc → dist/

Documentation

Full setup, configuration, and API reference: docs.insito.app