Kavchat by maxsave
Menu des guides

Android

La bibliothèque Android de Kavchat ajoute à votre application un bot d’assistance basé sur des scripts, avec des composants Jetpack Compose et une Activity pour les applications utilisant Views. Les réponses sont prévisibles et restent disponibles hors ligne à partir de la dernière version publiée. Android 6.0 (API 23) ou version ultérieure est requis.

Elle comprend deux modules : kavchat-engine, une version Kotlin/JVM du moteur de conversation, sans dépendance à Android ni à des bibliothèques tierces, et kavchat, qui inclut les communications réseau (HttpURLConnection), le cache sur l’appareil (SharedPreferences), les composants Compose KavchatChat et KavchatLauncher, ainsi que KavchatActivity.

Installation

Gradle (Kotlin DSL)
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.kavchat:kavchat-android:0.0.11")
}

La bibliothèque est distribuée via JitPack. Ajoutez son dépôt une seule fois, à côté de google() et de mavenCentral(). Le SDK est open source, sous licence MIT : bitbucket.org/maxsave/kavchat-android.

La bibliothèque déclare elle-même l’autorisation INTERNET et KavchatActivity dans son manifeste. Vous n’avez rien à ajouter manuellement.

Configuration

Appelez configure une seule fois, dans Application.onCreate :

Kotlin
class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Kavchat.configure(this, publicKey = "pk_live_...")
        // Optional: Kavchat.configure(this, "pk_live_...", apiBase = "https://api.kavchat.com", locale = "he")
    }
}

Vous pouvez inclure la clé publique dans l’application. N’y incluez jamais la clé secrète (sk_live_...).

Compose

Un bouton flottant, placé dans le coin choisi dans le tableau de bord, ouvre le chat en plein écran :

Compose
KavchatOverlay(Modifier.fillMaxSize()) {
    AppContent()
}

Vous pouvez aussi placer le bouton vous-même ou intégrer le chat dans votre propre écran :

Compose
KavchatLauncher()                                    // com.kavchat.ui.KavchatLauncher
KavchatChat(Modifier.fillMaxSize())                  // full chat, no close button
KavchatChat(Modifier.fillMaxSize(), onClose = { navController.popBackStack() })

Pour ouvrir et fermer le chat du bouton flottant depuis le code, utilisez Kavchat.controller.setPresented(true) et setPresented(false).

Views (sans Compose dans votre application)

Kotlin
Kavchat.open(context)                                // starts KavchatActivity

Depuis Java : Kavchat.open(context);. L’Activity utilise Compose en interne, mais votre application n’a pas besoin de l’utiliser.

Jeton d’identité

Identifiez un utilisateur connecté avec un JWT signé par votre serveur à l’aide de la clé secrète (voir Identification des utilisateurs). Le jeton est envoyé dans l’en-tête Authorization: Bearer <token>. Un utilisateur identifié peut consulter les versions réservées aux testeurs et envoyer le formulaire de contact sans adresse e-mail ni numéro de téléphone.

Kotlin
Kavchat.setUser(token = identityToken, name = "Dana")   // after login
Kavchat.setUser(token = null)                           // after logout

Un changement d’utilisateur recharge la version et démarre une nouvelle conversation. La conversation d’un utilisateur ne s’affiche donc pas chez un autre.

Écrans de l’application : onScreen

Dans un script, un bouton de type screen demande à l’application d’ouvrir l’un de ses écrans. Le chat se ferme d’abord (la boîte de dialogue de KavchatLauncher ou KavchatActivity) pour que l’écran soit visible :

Kotlin
Kavchat.onScreen = { screen, targetId ->
    navController.navigate("$screen/${targetId.orEmpty()}")   // e.g. "orders", "42"
}

Sans gestionnaire, ces boutons n’ont aucun effet. Les boutons link ouvrent uniquement les liens https (dans le navigateur) et tel (dans le composeur téléphonique). Pour l’analyse des données, Kavchat.onEvent signale les événements Ready, Unavailable, Open, Close, Effect et Ticket.

Liste des écrans dans l’éditeur

Déclarez une seule fois les écrans que l’application peut ouvrir dans Kavchat.configure(..., screens = ...) (type KavchatAppScreen). Le SDK envoie automatiquement 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 mènent à un écran non déclaré. Personne n’a à saisir manuellement la liste des écrans dans le tableau de bord.

Kotlin
Kavchat.configure(
    this, publicKey = "pk_live_...",
    screens = listOf(
        KavchatAppScreen("orders", "My orders"),
        KavchatAppScreen("product", "Product page", needsTarget = true),   // needs a targetId
    ),
)
// or later: Kavchat.registerScreens(listOf(...))
  • 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 liste peut contenir jusqu’à 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 si elle a changé ou une fois par semaine. En cas d’échec, aucune erreur n’est affichée et l’envoi est retenté au prochain lancement. L’utilisateur ne voit rien.
  • Les écrans enregistrés apparaissent dans le tableau de bord sous Bot, Paramètres, « Écrans de l’application », avec les plateformes ayant signalé chaque écran. Vous pouvez y supprimer un écran retiré de l’application.

Couleurs

Les couleurs proviennent du tableau de bord (primaryColor). Le texte affiché sur la couleur de marque est blanc ou presque noir, selon le contraste WCAG. Une couleur trop claire pour du texte sur fond blanc est remplacée par du presque noir dans les liens et les boutons. Le nom du bot, le sous-titre, l’image et le côté du bouton flottant (start ou end) proviennent aussi du tableau de bord : ils peuvent donc changer sans mise à jour de l’application. Les surfaces et la typographie reprennent votre MaterialTheme.

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

Langues et RTL

  • La langue de l’interface est celle du paramètre locale transmis à configure. Si ce paramètre est absent, la langue de l’appareil est utilisée si une traduction existe (he, en, ar, ru, es, fr, de, pt, it, tr), puis la langue du script et, en dernier recours, l’anglais.
  • La recherche de correspondance utilise toujours la langue du script (mots courants ignorés et préfixes en hébreu et en arabe).
  • En hébreu et en arabe, LocalLayoutDirection est défini sur RTL pour l’ensemble du chat. Rien n’est inversé manuellement : si vous encapsulez les composants, utilisez start et end. Conservez android:supportsRtl="true" dans le manifeste de l’application.

Réponses IA (Premium)

Vous n’avez 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 mention « Réponse IA » dans la langue de l’interface. Elle est suivie d’un bouton vers un sujet connexe, s’il y en a un, et d’un bouton « Contacter l’équipe ».

S’il n’y a pas de réponse, 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.

Chat avec un conseiller

Vous n’avez rien à configurer dans l’application. Lorsque vous activez le chat avec des conseillers dans l’interface d’administration, le chat de l’application fonctionne exactement comme le widget du site.

  • L’option apparaît uniquement si le chat avec des conseillers est activé dans la version publiée. Lorsque le bot affiche « Contacter l’équipe », le SDK vérifie si un conseiller est disponible. Le résultat est mis en cache pendant 30 secondes. Si un conseiller est disponible, un bouton « Parler à un conseiller » apparaît avant ce bouton. Sinon, seul le formulaire de contact est affiché. Une courte ligne au-dessus explique pourquoi : en dehors des heures d’ouverture (avec l’heure de reprise) ou tous les conseillers sont occupés.
  • Avant la conversation, l’utilisateur remplit un court formulaire : nom, adresse e-mail ou numéro de téléphone, service (uniquement si plusieurs services sont ouverts) et premier message facultatif. Un visiteur non identifié doit laisser une adresse e-mail ou un numéro de téléphone. Un utilisateur identifié par un jeton d’identité n’a à fournir ni l’un ni l’autre. Si aucun conseiller n’est plus disponible au moment de l’envoi, le formulaire de contact s’ouvre avec les informations déjà saisies.
  • Pendant l’attente, le temps restant avant la conversion de la conversation en ticket s’affiche, ainsi qu’un bouton « Laisser plutôt un message ». Le délai d’attente se règle dans l’interface d’administration et vaut 2 minutes par défaut. L’utilisateur peut écrire pendant l’attente, et le conseiller verra ses messages. Si aucun conseiller ne se libère à temps, la conversation est enregistrée comme un ticket classique et son numéro s’affiche.
  • Pendant la conversation, le chat affiche le nom du conseiller, un message lorsqu’un conseiller rejoint la conversation (y compris après un transfert), un indicateur de saisie et un bouton pour terminer la conversation. Les messages contiennent uniquement du texte brut, jusqu’à 2000 caractères, sans liens. Un message qui n’est pas encore parvenu au serveur porte la mention « Envoi... ». Après plusieurs échecs, l’utilisateur peut appuyer sur le message pour réessayer. Une nouvelle tentative ne crée pas de doublon.
  • Après chaque déconnexion, le SDK attend un peu, récupère les éléments manqués et se reconnecte. Le délai d’attente augmente progressivement. Les messages sont toujours affichés dans l’ordre et sans doublons. Si la connexion continue échoue (par exemple, derrière un proxy d’entreprise), le SDK passe temporairement à des vérifications répétées auprès du serveur.
  • Lorsque l’application passe en arrière-plan, la connexion se ferme. Au retour dans l’application, le SDK récupère les éléments manqués et se reconnecte. Une conversation en cours se poursuit même après la fermeture et le redémarrage de l’application, tant que 12 heures ne se sont pas écoulées.
  • Cette version ne propose pas de notifications push. Les messages arrivent uniquement lorsque l’application est ouverte. Une réponse envoyée pendant que l’application est en arrière-plan apparaît dès le retour dans l’application.
  • Les données d’accès à la conversation sont conservées en mémoire. Sur l’appareil, elles ne sont enregistrées que sous forme chiffrée avec une clé Android Keystore. Elles ne sont inscrites ni dans une URL ni dans les journaux. Elles sont supprimées lorsque la conversation se termine, devient un ticket ou expire, ainsi que lors d’un changement d’utilisateur avec setUser.

Vous pouvez utiliser Kavchat.controller.livePage pour indiquer au conseiller depuis quel écran l’utilisateur est arrivé.

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 libre), choisir la suite en fonction des informations connues et envoyer une fiche prospect.

  • 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. Pour une question portant sur le nom, le clavier met la première lettre de chaque mot en majuscule. Si la réponse n’est pas valide, le bot affiche un court message dans la langue du chat et le champ est signalé. Un bouton « Passer » apparaît pour les questions facultatives. Saisir « Annuler » dans l’une des langues prises en charge permet de quitter la question.
  • Téléphone : les numéros sans + sont associés au pays par défaut de l’espace de travail, défini dans les paramètres de l’interface d’administration.
  • Prospect : une étape de collecte de prospect affiche le texte de consentement avec les boutons « Envoyer » et « Non, merci », puis le message de confirmation. La fiche prospect est mise en file d’attente sur l’appareil, puis envoyée au serveur. En l’absence de réseau ou si le serveur est indisponible, l’envoi est retenté, y compris au prochain lancement et après reload(). Le serveur ignore les doublons.
  • Préremplissage : le formulaire de contact et le formulaire de demande de chat avec un conseiller sont préremplis avec le nom, l’adresse e-mail et le numéro de téléphone recueillis. Toutes les valeurs recueillies sont jointes au ticket ou à la demande de chat avec un conseiller. Les questions préalables au chat avec un conseiller (Premium) sont posées avant la mise en relation.
  • Jeton d’identité : lorsque vous utilisez setUser, les champs name, email et phone du jeton renseignent les réponses aux questions correspondantes, que le bot ignore alors.
  • Écran actuel : les conditions peuvent vérifier l’écran actuel. Définissez Kavchat.controller.livePage (par exemple, "checkout").

Les valeurs recueillies sont des données personnelles. Elles restent dans la conversation enregistrée sur l’appareil et sont transmises uniquement avec les fiches prospects, les tickets et les conversations avec un conseiller, jamais dans les rapports.

Fonctionnement hors ligne et cache

La dernière version est conservée dans SharedPreferences avec son ETag, puis vérifiée à chaque lancement avec If-None-Match (304). En l’absence de réseau, la copie en cache est utilisée et un message le signale. Lorsque le bot est désactivé, réservé aux testeurs ou que le quota est épuisé, rien ne s’affiche. Une conversation en cours est conservée jusqu’à 30 minutes d’inactivité : quitter le chat ou l’application ne la fait donc pas recommencer. Le parcours de la conversation est transmis deux secondes après la dernière action, et immédiatement lorsque l’application passe en arrière-plan.