Kavchat by maxsave
Menu des guides

iOS

Le package Swift de Kavchat ajoute à votre application iOS un bot d’assistance basé sur des scripts, avec des composants SwiftUI et UIKit. Les réponses sont prévisibles et restent disponibles hors ligne à partir de la dernière version publiée. Nécessite iOS 15 ou une version ultérieure.

Le package comprend deux produits : KavchatEngine, une version Swift du moteur de conversation, sans UIKit, et Kavchat, qui inclut les communications réseau, le cache sur l’appareil et l’interface : KavchatChatView (SwiftUI), KavchatLauncher et KavchatViewController (UIKit).

Installation

Avec Swift Package Manager dans Xcode : choisissez File > Add Package Dependencies, puis saisissez l’URL du dépôt :

Package URL
https://bitbucket.org/maxsave/kavchat-ios.git

Ou dans le fichier Package.swift :

Package.swift
.package(url: "https://bitbucket.org/maxsave/kavchat-ios.git", from: "0.0.11"),
// ...
.product(name: "Kavchat", package: "kavchat-ios"),

Le SDK est open source, sous licence MIT : bitbucket.org/maxsave/kavchat-ios.

Configuration

Appelez configure une seule fois, le plus tôt possible, par exemple dans l’initialiseur de votre App ou dans application(_:didFinishLaunchingWithOptions:) :

Swift
import Kavchat

Kavchat.configure(publicKey: "pk_live_...")            // the public key from the dashboard
// Optional:
// Kavchat.configure(publicKey: "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_...).

SwiftUI

Un bouton flottant, placé dans le coin choisi dans le tableau de bord, ouvre le chat dans une fenêtre modale (sheet) :

SwiftUI
ContentView()
    .kavchatLauncher()

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

SwiftUI
KavchatLauncher()
KavchatChatView()                                      // full chat, no close button
KavchatChatView(onClose: { showChat = false })         // with a close button

Ouvrez et fermez la fenêtre du bouton flottant depuis le code avec Kavchat.open() et Kavchat.close().

UIKit

UIKit
Kavchat.present(from: self)                            // modal, with a close button
// or
let chat = KavchatViewController(showsCloseButton: false)
navigationController?.pushViewController(chat, animated: true)

Jeton d’identité

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

Swift
Kavchat.setUser(token: identityToken, name: "Dana")    // after login
Kavchat.setUser(token: nil)                            // after logout

Changer d’utilisateur recharge la version et démarre une nouvelle conversation, pour que la conversation d’un utilisateur ne s’affiche pas chez un autre.

Écrans de l’application : onScreen

Un bouton de type screen dans un script demande à l’application d’ouvrir l’un de ses écrans. La fenêtre du chat se ferme d’abord pour laisser l’écran visible :

Swift
Kavchat.onScreen = { screen, targetId in
    router.open(screen, id: targetId)                  // e.g. "orders", "42"
}

Sans gestionnaire, ces boutons n’ont aucun effet. Les boutons link ouvrent uniquement les liens https et tel. 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:). Le SDK envoie lui-même cette liste à Kavchat. L’éditeur de scripts propose alors ces écrans par leur nom dans une liste déroulante, au lieu 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.

Swift
Kavchat.configure(publicKey: "pk_live_...", screens: [
    KavchatScreen(id: "orders", label: "My orders"),
    KavchatScreen(id: "product", label: "Product page", needsTarget: true),  // needs a targetId
])
// or later: Kavchat.registerScreens([...])
  • id est la valeur reçue par 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 la forme 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 prochain lancement. Rien n’est visible 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

Les couleurs proviennent du tableau de bord (primaryColor). Le texte 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 et peuvent donc changer sans mise à jour de 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.

Langues et RTL

  • La langue de l’interface est celle du paramètre locale transmis à configure. À défaut, 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 enfin l’anglais.
  • La recherche de correspondance avec le script 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, le layoutDirection de tout le chat va de droite à gauche. Rien n’est inversé manuellement : si vous placez les composants dans des conteneurs, utilisez leading et trailing.

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 écrit. 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 lié, s’il y en a un, et d’un bouton « Contacter l’équipe ».

En l’absence 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 son 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 les conseillers dans l’interface d’administration, le chat de l’application fonctionne exactement comme le widget du site.

  • L’option s’affiche uniquement si le chat avec les 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 conservé pendant 30 secondes. Si un conseiller est disponible, un bouton « Discuter avec un conseiller » s’affiche avant cette option. Sinon, seul le formulaire de contact s’affiche. Une courte ligne au-dessus explique pourquoi : les horaires d’ouverture sont dépassés (avec l’heure de reprise) ou tous les conseillers sont occupés.
  • Avant la conversation, l’utilisateur remplit un court formulaire : nom, e-mail ou téléphone, service (uniquement si plusieurs services sont ouverts) et premier message facultatif. Un visiteur doit laisser une adresse e-mail ou un numéro de téléphone. Un utilisateur identifié par un jeton d’identité n’a besoin de 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 ces 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 arrivé au serveur porte la mention « Envoi en cours... ». Après plusieurs échecs d’envoi, l’utilisateur peut toucher 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 s’affichent toujours dans l’ordre et sans doublons. Si la connexion continue ne fonctionne pas (par exemple derrière un proxy d’entreprise), le SDK passe temporairement à des interrogations répétées 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 ouverte reprend 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 s’affiche dès que l’utilisateur y revient.
  • Les informations d’accès à la conversation sont conservées uniquement en mémoire et dans le Keychain de l’appareil. Elles ne sont enregistrées ni dans UserDefaults, ni dans une URL, ni dans un journal. 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.shared.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 selon les informations connues et transmettre 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é. Les questions facultatives affichent un bouton « Passer ». Saisir « Annuler » dans l’une des langues prises en charge permet de quitter la question.
  • Téléphone : un numéro sans + est associé 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 attente sur l’appareil et envoyée au serveur. En l’absence de connexion 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’e-mail et le téléphone recueillis. Toutes les valeurs recueillies sont jointes au ticket ou à la demande de chat avec un conseiller. Les questions préalables à une conversation avec un conseiller (Premium) sont posées avant la mise en relation.
  • Jeton d’identité : avec setUser, les champs name, email et phone du jeton renseignent les réponses aux questions correspondantes, et le bot passe ces questions.
  • Écran actuel : les conditions peuvent vérifier l’écran actuel. Définissez Kavchat.shared.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 aux fiches prospects, aux tickets et aux conversations avec un conseiller, jamais aux rapports.

Fonctionnement hors ligne et cache

La dernière version est conservée dans UserDefaults avec son ETag, puis vérifiée à chaque lancement avec If-None-Match (304). Sans 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 ouverte 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.