React Native

Le package @kavchat/react-native ajoute à votre application le chat d’assistance basé sur des scripts : un Provider, un écran de chat et un bouton flottant en option. Les réponses proviennent des scripts que vous avez publiés dans le tableau de bord et s’exécutent sur l’appareil.

Installation

Le package est entièrement écrit en JavaScript, sans code natif propre ni bibliothèque d’icônes. Il fonctionne donc de la même façon dans une application React Native classique et dans Expo. Dépendances homologues : react à partir de la version 18 et react-native à partir de la version 0.72.

React Native CLI (sans Expo)

yarn add @kavchat/react-native @react-native-async-storage/async-storage
cd ios && pod install

AsyncStorage est un module natif : pod install assure sa liaison sur iOS, et la liaison est automatique sur Android.

Expo

Le package fonctionne dans Expo Go et dans les builds de développement :

yarn add @kavchat/react-native
npx expo install @react-native-async-storage/async-storage

Sans AsyncStorage

AsyncStorage conserve la version publiée et la conversation entre les lancements. Son installation est facultative : sans lui, le package garde tout en mémoire. Le bot fonctionne, mais télécharge à nouveau la version à chaque lancement. Pour utiliser un autre stockage, comme MMKV, passez à la prop storage un objet { getItem, setItem, removeItem? }, synchrone ou asynchrone :

import { MMKV } from 'react-native-mmkv';
const mmkv = new MMKV();
const storage = {
  getItem: (k: string) => mmkv.getString(k) ?? null,
  setItem: (k: string, v: string) => mmkv.set(k, v),
  removeItem: (k: string) => mmkv.delete(k),
};

<KavchatProvider publicKey="pk_live_..." storage={storage}>

Utilisation

import { KavchatProvider, KavchatChat, KavchatLauncher, useKavchat } from '@kavchat/react-native';

export default function App() {
  return (
    <KavchatProvider publicKey="pk_live_..." onScreen={(screen, id) => navigation.navigate(screen, { id })}>
      <Navigation />
      {/* floating button, bottom end corner; opens the chat in a modal */}
      <KavchatLauncher />
    </KavchatProvider>
  );
}

// or as a screen in your own navigator
function SupportScreen() {
  return <KavchatChat />;
}

// or your own button
function HelpButton() {
  const { available, open } = useKavchat();
  if (!available) return null; // bot is off, limited to testers, or over quota
  return <Button title="Help" onPress={open} />;
}

Props de KavchatProvider

useKavchat() renvoie { status, available, offline, locale, isOpen, open, close, toggle, setUser, startNewConversation, openContactForm, controller }.

Props de KavchatChat : onClose? (affiche un bouton de fermeture), hideHeader? et style?. Props de KavchatLauncher : style? (position), onPress? (pour ouvrir votre propre écran à la place de la fenêtre intégrée) et attention? (false désactive le message).

Lorsqu’un message à côté du bouton de chat est configuré dans l’interface d’administration (bulle de dialogue ou texte en arc au-dessus du bouton), KavchatLauncher l’affiche après le délai défini, au maximum une fois par jour. Fermer le message ou ouvrir le chat le masque jusqu’au lendemain. Le message ne s’affiche pas lorsque le chat est ouvert. Si la réduction des animations est activée sur l’appareil, le message s’affiche sans animation. Lorsque l’option « Ne pas afficher sur les téléphones » est activée, le message s’affiche uniquement sur les tablettes (dont le côté le plus court de l’écran mesure au moins 600 points).

Jeton d’identité

Sans jeton, l’utilisateur est un invité et le formulaire de contact lui demande une adresse e-mail ou un numéro de téléphone. Pour identifier un utilisateur connecté, signez un JWT à courte durée de validité sur votre serveur avec la clé secrète (jamais dans l’application, voir Identification des utilisateurs), puis transmettez-le ainsi :

<KavchatProvider publicKey="pk_live_..." userToken={session?.kavchatToken} userName={session?.firstName}>

Une modification de userToken (connexion ou déconnexion) recharge la version, car l’appartenance au groupe d’utilisateurs de test dépend de l’identité de l’utilisateur. Vous pouvez aussi appeler useKavchat().setUser({ token, name }). Le jeton est envoyé uniquement dans l’en-tête Authorization: Bearer et n’est pas stocké sur l’appareil. Une conversation enregistrée est liée à une empreinte du jeton : un autre utilisateur sur le même appareil commence donc une nouvelle conversation.

Liens, écrans et formulaire de contact

• Les boutons de type link ouvrent uniquement les URL https: et tel:, via Linking.openURL. Les autres types d’URL ne sont pas ouverts.
• Les boutons de type screen appellent onScreen. Le chat reste là où il était.
• Le bouton « Contacter l’équipe » ouvre le formulaire de contact avec la conversation jointe. Le numéro du ticket s’affiche après l’envoi.

Liste des écrans dans l’éditeur

Déclarez une seule fois les écrans que l’application peut ouvrir dans la prop screens de KavchatProvider. Le SDK envoie lui-même la liste à Kavchat. L’éditeur de scripts propose alors ces écrans avec leurs noms dans une liste déroulante, à la place d’un champ de texte libre. Il demande aussi un identifiant d’élément lorsqu’un écran en a besoin et signale les boutons qui pointent vers un écran non déclaré. Personne n’a besoin de saisir manuellement la liste des écrans dans le tableau de bord.

const screens = [
  { id: 'orders', label: 'My orders' },
  { id: 'product', label: 'Product page', needsTarget: true }, // the button also carries a product id
];

<KavchatProvider
  publicKey="pk_live_..."
  screens={screens}
  onScreen={(screen, targetId) => navigation.navigate(screen, targetId ? { id: targetId } : undefined)}
>

• id est la valeur transmise à onScreen : lettres latines, chiffres, _, . et -, jusqu’à 40 caractères. label est le nom affiché à l’administrateur, jusqu’à 60 caractères. La limite est de 100 écrans. Les entrées non valides et les identifiants en double sont ignorés.
• needsTarget : le bouton contient aussi un identifiant d’élément (par exemple, un identifiant de produit), transmis à onScreen sous le nom targetId.
• La liste est envoyée en arrière-plan après le chargement de la version, uniquement lorsqu’elle a changé ou une fois par semaine. Un échec passe inaperçu et l’envoi est retenté au lancement suivant. Rien ne s’affiche pour l’utilisateur.
• Les écrans enregistrés apparaissent dans le tableau de bord sous Bot, Paramètres, « Écrans de l’application », avec les plateformes qui ont signalé chaque écran. Vous pouvez y supprimer un écran retiré de l’application.

Couleurs et RTL

Les couleurs proviennent des paramètres du bot dans le tableau de bord (primaryColor). La couleur du texte affiché sur cette couleur est choisie selon le contraste WCAG. Vous pouvez personnaliser chacune d’elles : primary, background, botBubble, userBubble, text, muted, accent, onPrimary et error :

<KavchatProvider
  publicKey="pk_live_..."
  theme={{ primary: '#0f766e', background: '#ffffff' }}
>

Le package ne modifie pas le sens de mise en page de l’application. Il suit I18nManager.isRTL (styles start et end), et chaque texte est aligné selon sa langue. L’hébreu et l’arabe restent donc lisibles dans une application affichée de gauche à droite. Si votre application est en hébreu ou en arabe, configurez le RTL une seule fois, comme d’habitude : I18nManager.forceRTL(true), puis redémarrez l’application.

Le badge « Propulsé par Kavchat by maxsave » s’affiche dans toutes les offres, avec un lien vers kavchat.com. Avec Premium, vous pouvez le masquer dans les paramètres du bot.

Chat avec un conseiller

Aucune configuration n’est nécessaire pour commencer. Lorsque vous activez le chat avec des conseillers dans l’interface d’administration, l’option apparaît dans le chat de l’application, comme dans le widget du site.

• L’option : « Parler à un conseiller » apparaît avant « Contacter l’équipe », uniquement après confirmation par le serveur qu’un conseiller est disponible. La disponibilité est vérifiée à nouveau lorsque l’utilisateur appuie sur le bouton. En dehors des horaires d’ouverture, ou lorsque tous les conseillers sont occupés, seul le formulaire de contact est proposé, avec une courte explication et l’heure de retour de l’équipe, si elle est connue. Lorsque le quota mensuel est épuisé, le formulaire s’affiche sans explication.
• La demande : les invités laissent une adresse e-mail ou un numéro de téléphone au cas où aucun conseiller ne se libérerait à temps. Ils peuvent aussi ajouter un nom et un premier message. Si plusieurs services sont ouverts, ils en choisissent un. Les utilisateurs identifiés (userToken) n’ont pas à saisir leurs coordonnées. Si aucun conseiller ne peut prendre la conversation, le formulaire de contact s’ouvre avec les informations déjà saisies.
• L’attente : le message « En attente d’un conseiller » s’affiche avec un compte à rebours jusqu’à la fin du délai d’attente que vous avez défini, accompagné des boutons « Laisser plutôt un message » et « Terminer la conversation ». L’utilisateur peut déjà écrire pendant l’attente. À la fin du délai, la conversation est automatiquement convertie en ticket. Le numéro du ticket s’affiche avec une explication indiquant qu’aucun conseiller ne s’est libéré à temps.
• La conversation : nom du conseiller, messages, indicateur de saisie, transfert à un autre conseiller et fin de la conversation. Tout ce qui provient du serveur s’affiche en texte brut, sans liens.
• En temps réel : connexion Server-Sent Events via XMLHttpRequest (ou fetch en streaming, lorsqu’il est disponible). Si la connexion est interrompue, le chat se reconnecte à intervalles croissants et récupère tout ce qui a été manqué. Ainsi, aucun message n’est perdu ni affiché deux fois. Sur les réseaux qui bloquent cette connexion, le chat passe à des requêtes répétées (long-poll). Chaque message possède un identifiant : une nouvelle tentative ne crée donc pas de doublon. Un message non envoyé est signalé et peut être renvoyé d’un simple appui.
• Passage en arrière-plan et redémarrage : lorsque l’application passe en arrière-plan, la connexion est fermée. À son retour, le chat récupère ce qui a été manqué. Le jeton d’accès à la conversation reste valide jusqu’à 12 heures ou jusqu’à la fin de la conversation, et est conservé dans le stockage de votre choix. Ainsi, une conversation en cours réapparaît à l’écran après le redémarrage de l’application. Le jeton n’est pas conservé dans une URL ni écrit dans les journaux.
• Pas de notifications push dans cette version : les messages du conseiller arrivent uniquement lorsque l’application est ouverte.

Il est recommandé de conserver le jeton d’accès dans un stockage sécurisé (Keychain sur iOS, Keystore sur Android). Si vous ne définissez pas secureStorage, le jeton est conservé dans le même stockage que la conversation. Votre propre bouton de chat avec un conseiller ouvre le formulaire de demande lorsqu’un conseiller est disponible. Sinon, le formulaire de contact s’ouvre avec l’explication :

import * as SecureStore from 'expo-secure-store';

// expo-secure-store allows only [A-Za-z0-9._-] in keys
const safe = (k: string) => k.replace(/[^A-Za-z0-9._-]/g, '_');
const secureStorage = {
  getItem: (k: string) => SecureStore.getItemAsync(safe(k)),
  setItem: (k: string, v: string) => SecureStore.setItemAsync(safe(k), v),
  removeItem: (k: string) => SecureStore.deleteItemAsync(safe(k)),
};

<KavchatProvider publicKey="pk_live_..." secureStorage={secureStorage} livePage="checkout">

// your own button
const { openLive } = useKavchat();
<Button title="Chat with us" onPress={openLive} />

Événements : onEvent reçoit { type: 'live', phase } à chaque changement d’état de la conversation (queued, active, closed, ticket, replaced, expired).

Questions, conditions et prospects

Aucune configuration n’est nécessaire dans l’application. Un script peut demander des informations (nom, téléphone, e-mail, nombre ou texte), déterminer la suite selon des conditions (Premium) et transmettre les données d’un prospect. Tout s’exécute sur l’appareil.

• Clavier adapté : lorsque le bot attend une réponse, le champ de texte affiche un clavier adapté au téléphone, à l’e-mail ou aux nombres, avec saisie semi-automatique. Si la réponse n’est pas valide, le bot explique ce qui manque et le champ est signalé. Les questions facultatives affichent un bouton « Passer ».
• Prospect : lorsqu’un texte de consentement est présent, les boutons « Envoyer » et « Non, merci » s’affichent. Sans connexion réseau, les données du prospect sont conservées sur l’appareil et envoyées au retour de la connexion, sans doublons.
• Préremplissage : les réponses déjà fournies par l’utilisateur préremplissent le formulaire de contact et le formulaire de demande de chat avec un conseiller. Elles sont jointes au ticket et à la conversation avec le conseiller. Le nom, l’adresse e-mail et le numéro de téléphone provenant du jeton d’identité sont considérés comme des réponses connues : le bot ne les demande pas à nouveau.
• Écran actuel : livePage indique aussi l’écran vérifié par les conditions et transmis avec les données des prospects. Une modification de la prop le met à jour.

Réponses IA (Premium)

Rien à configurer dans l’application. Lorsque vous activez les réponses IA dans l’interface d’administration (avec votre propre clé de fournisseur d’IA), une question à laquelle aucun script ne répond est envoyée à Kavchat. Pendant l’attente, jusqu’à 20 secondes, le chat indique que le bot est en train d’écrire. La réponse s’affiche en texte brut avec une petite étiquette « Réponse IA » dans la langue de l’interface, suivie d’un bouton vers un sujet associé, s’il y en a un, et du bouton « Contacter l’équipe ».

Si aucune réponse n’est disponible, ou si la requête échoue, prend trop de temps ou dépasse la limite (10 réponses par conversation toutes les 15 minutes), le chat affiche le message habituel « Je n’ai pas trouvé de réponse ». La question figure toujours dans le rapport des questions sans réponse, et les réponses IA sont conservées dans la conversation enregistrée comme tout autre message.

Comportement

• La version publiée est mise en cache avec son ETag (If-None-Match, 304). Sans connexion réseau, la version en cache s’affiche avec un message qui le signale.
• La conversation est enregistrée sur l’appareil et restaurée pendant 24 heures, tant que la version et l’utilisateur restent les mêmes.
• Le parcours de conversation est transmis 2 secondes après la dernière action, ainsi que lorsque l’application passe en arrière-plan.
• Les requêtes n’envoient aucun en-tête personnalisé, uniquement Authorization, Content-Type et If-None-Match.