@wekivo/react-native

SDK officiel React Native pour Kivo.

v0.1 — headless : identify + track + analytics. Pas de UI chat native dans cette version — <KivoChatScreen /> et <KivoLauncher /> viendront en v1.0.

Architecture 100 % native : pas de WebView. On utilise le client HTTP de @wekivo/core et @react-native-async-storage/async-storage pour la persistance.

Installation

npx expo install @wekivo/react-native @react-native-async-storage/async-storage

Ou en bare RN :

npm install @wekivo/react-native @react-native-async-storage/async-storage
cd ios && pod install

Setup

Wrappe ton App au niveau le plus haut :

import { KivoProvider } from '@wekivo/react-native';

export default function App() {
  return (
    <KivoProvider apiKey={process.env.EXPO_PUBLIC_KIVO_KEY!}>
      <NavigationContainer>
        <RootStack />
      </NavigationContainer>
    </KivoProvider>
  );
}

Au mount du Provider :

1. AsyncStorage est hydraté dans un cache mémoire sync.
2. L'ApiClient est instancié.
3. La session démarre (réutilise la précédente si < 30 min d'inactivité).
4. Si endUser est fourni, identify() est appelé.
5. Le batcher démarre (flush 5 s ou batch ≥ 20 events, flush forcé quand l'app passe en background).

Pendant ce boot, ready: false et les identify/track sont bufferisés.

Usage

import { useKivo } from '@wekivo/react-native';

function UpgradeButton({ plan }: { plan: string }) {
  const kivo = useKivo();
  return (
    <Pressable
      onPress={() =>
        kivo.track('upgrade_clicked', { plan, source: 'cta' })
      }
    >
      <Text>Passer en {plan}</Text>
    </Pressable>
  );
}

Identifier après login

const kivo = useKivo();

useEffect(() => {
  if (user) {
    void kivo.identify({
      externalId: user.id,
      email: user.email,
      traits: { plan: user.plan },
    });
  }
}, [user, kivo]);

Ou plus simple, passe endUser au Provider — il fera l'identify automatiquement et re-identify si externalId change.

Détection de langue Expo

Si tu utilises expo-localization, branche-le :

import * as Localization from 'expo-localization';

<KivoProvider
  apiKey={...}
  detectLanguage={() => Localization.locale?.split('-')[0] ?? null}
>

Le header X-Kivo-Lang sera envoyé à chaque requête et le backend adaptera la réponse de l'assistant.

API

<KivoProvider>

| Prop | Type | Défaut | Description | | ----------------- | --------------------------------- | --------- | ----------- | | apiKey | string | — | Clé tenant kv_*. Requis. | | host | string | https://api.wekivo.com | Override host API. | | endUser | IdentifyPayload | — | Identifie au mount. | | detectLanguage | () => string \| null | — | Détecteur de langue (Expo Localization, etc.). | | userAgent | string | <os> <version> | Override du User-Agent. | | batchInterval | number | 5000 | Délai flush en ms. | | batchSize | number | 20 | Taille max batch. | | debug | boolean | false | Logs verbeux. | | onReady | (session) => void | — | Callback session prête. | | onError | (error) => void | — | Callback erreur init. |

useKivo()

Retourne :

{
  identify(user): Promise<void>;
  track(name, payload?): void;
  reset(): void;
  ready: boolean;
  session: KivoRNSession | null;
  error: Error | null;
}

Comportement clé

• AsyncStorage : hydraté une fois au boot, puis cache mémoire sync pour la session. Les writes sont propagés en fire-and-forget vers le disque.
• Background flush : AppState listener déclenche un flush quand l'app passe au second plan.
• Session 30 min idle : si l'app n'a pas tracké pendant 30 min, une nouvelle session est créée au réveil.
• Buffer pré-ready : identify/track appelés avant ready sont mis en queue dans un buffer global au Provider et rejoués dans l'ordre.

Compatibilité runtime

JS engine — Hermes est fortement recommandé (défaut sur RN ≥ 0.74 et Expo SDK ≥ 49). Le streaming SSE utilise fetch().body.getReader() qui est stable sur Hermes ; sur JSC le comportement varie selon la version RN. Si tu désactives Hermes manuellement, teste le streaming soigneusement ou utilise react-native-sse en remplacement.

Versions testées :

• Expo SDK 50, 51, 52 — OK
• RN 0.74, 0.75, 0.76 (Hermes) — OK
• RN < 0.74 — non supporté (peer dep react-native >=0.74.0)

iOS / Android :

• iOS ≥ 13 (Modal pageSheet natif)
• Android ≥ 7 / API 24 (Animated useNativeDriver stable)

Sur Android < 13, le bug RN connu de FlatList inverted + removeClippedSubviews est neutralisé automatiquement (le flag est désactivé sur Android — au prix d'une consommation mémoire un peu plus élevée sur les longues conversations).

Roadmap v1.0

• <KivoChatScreen /> — composant écran natif chat (FlatList, KeyboardAvoidingView, SafeArea).
• <KivoLauncher /> — bouton flottant natif (Animated).
• Stream SSE des réponses AI (react-native-sse polyfill).
• Push notifications natives sur message agent humain.

Voir aussi

• Documentation
• @wekivo/core — noyau partagé
• @wekivo/react — SDK React web