SDK de chat pour iOS et Android

Placez votre chat en direct Deskwoot dans votre propre application iOS ou Android, comme un écran natif. Votre équipe et votre bot IA y répondent dans Deskwoot, comme pour le chat de votre site.

Sur cette page

Ce qu'est le SDK

Le SDK place le chat de la boîte de réception de votre site dans votre application, comme un écran natif. Il est dessiné avec UIKit sur iOS et avec les vues d'Android sur Android, et non chargé comme une page web ; seul le texte d'un article d'aide s'affiche dans une web view du système. Les visiteurs écrivent à votre équipe et à votre bot IA, cherchent dans votre centre d'aide et lisent les réponses directement dans votre application.

C'est le même chat que sur votre site. Il lit les mêmes réglages de la boîte de réception (couleur de marque, textes, équipe, bot IA, centre d'aide) et affiche l'apparence choisie pour la boîte : Épuré, Accueil ou Direct. Il parle les 10 langues visiteurs du chat de votre site.

Les conversations venues de l'application arrivent dans cette boîte de réception, où votre équipe leur répond comme d'habitude.

Prérequis

PlateformeFonctionne surSe compile avec
iOSiOS 15 ou ultérieur, iPhone et iPadXcode 15 ou ultérieur (Swift 5.9)
AndroidAndroid 5.0 (API 21) ou ultérieurcompileSdk 34 ou plus, Android Gradle Plugin 8 ou ultérieur, Kotlin 1.9 ou ultérieur, ou Java. Fonctionne dans les applications construites avec Views comme avec Jetpack Compose.

Il vous faut aussi une boîte de réception Deskwoot de type Chat en direct (le chat du site). Le SDK utilise son jeton du widget.

Installation

iOS : dans Xcode, choisissez File → Add Package Dependencies, saisissez https://github.com/Deskwoot/deskwoot-ios et ajoutez la bibliothèque Deskwoot à la cible de votre application. Ou ajoutez le paquet à votre Package.swift :

iOS (Swift)
dependencies: [
    .package(url: "https://github.com/Deskwoot/deskwoot-ios", from: "1.0.0"),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [.product(name: "Deskwoot", package: "deskwoot-ios")]
    ),
]

Android : le SDK est sur Maven Central. Ajoutez-le au build.gradle.kts du module de votre application :

Android (Kotlin)
dependencies {
    implementation("com.deskwoot:deskwoot-android:1.0.0")
}

Le paquet iOS est livré en code source et se compile avec votre Xcode. La bibliothèque Android fonctionne depuis Kotlin et depuis Java.

Configuration

Le SDK a besoin du jeton du widget d'une boîte de réception de type Chat en direct. Dans Deskwoot, ouvrez Paramètres → Boîtes de réception → votre boîte de réception → Chat dans votre application iOS et Android : le jeton est en haut, prêt à copier.

Appelez setup une fois avec ce jeton, aussi tôt que vous le souhaitez : dans application(_:didFinishLaunchingWithOptions:) sur iOS, dans Application.onCreate sur Android. Il ne fait aucun accès disque ni réseau sur le thread principal, et un second appel avec le même jeton ne fait rien.

iOS (Swift)
import Deskwoot
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Deskwoot.setup(widgetToken: "YOUR_WIDGET_TOKEN")
        return true
    }
}
Android (Kotlin)
import android.app.Application
import com.deskwoot.sdk.Deskwoot

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Deskwoot.setup(this, "YOUR_WIDGET_TOKEN")
    }
}

Sur iOS, appelez le SDK depuis le thread principal (un appel depuis un autre thread est journalisé et s'exécute sur le thread principal un instant plus tard). Sur Android, chaque appel fonctionne depuis n'importe quel thread.

Un widgetToken = une boîte de réception. Avec le jeton de votre site, les chats de l'application arrivent dans la même boîte de réception que ceux du site. Avec le jeton d'une deuxième boîte de chat en direct, vous les gardez séparés.

Ouvrir le chat

Ouvrez le chat depuis votre propre bouton d'aide. Chaque appel fonctionne juste après setup, même avant le chargement des réglages de la boîte de réception.

iOSAndroidCe qui s'ouvre
present()present(activity)La page d'accueil.
presentConversation()presentConversation(activity)La conversation en cours la plus récente du visiteur, ou une nouvelle.
presentNewConversation(text:)presentNewConversation(activity, text)Une nouvelle conversation avec votre texte dans le champ du message. Le visiteur peut le modifier et l'envoie lui-même ; le SDK n'envoie rien à sa place.
presentHelpCenter()presentHelpCenter(activity)Le centre d'aide, ou la page d'accueil si la boîte de réception n'en a pas.
dismiss()dismiss()Ferme le chat s'il est ouvert.

Sur iOS, le chat s'ouvre en feuille au-dessus de l'écran visible de votre application ; passez from: pour choisir l'écran. Sur Android, il s'ouvre dans sa propre Activity ; passez l'Activity depuis laquelle vous appelez : le chat reste alors dans la tâche de votre application et reprend son mode clair ou sombre.

iOS (Swift)
// For example behind your "Help" button
Deskwoot.present()                       // the start page
Deskwoot.present(from: self)             // the same, over this screen
Deskwoot.presentConversation()
Deskwoot.presentNewConversation(text: "I have a question about order 1042")
Deskwoot.presentHelpCenter()
Deskwoot.dismiss()
Android (Kotlin)
// In an Activity, for example behind your "Help" button
Deskwoot.present(this)                   // the start page
Deskwoot.presentConversation(this)
Deskwoot.presentNewConversation(this, "I have a question about order 1042")
Deskwoot.presentHelpCenter(this)
Deskwoot.dismiss()

Le bouton du chat

setLauncherVisible(true) affiche le bouton rond du chat du widget web au-dessus du contenu de votre application : dans votre couleur de marque, du côté choisi pour la boîte de réception, avec un badge pour les réponses non lues. Un appui ouvre le chat. Il est masqué par défaut, car la plupart des applications ouvrent le chat depuis leur propre bouton.

Une réponse quand le chat est fermé

Quand une réponse arrive pendant que votre application est ouverte et le chat fermé, une petite carte glisse en bas de votre application avec la photo et le nom de la personne qui a écrit et 2 lignes de la réponse. Un appui ouvre cette conversation. La carte ne demande aucune autorisation et ne s'affiche jamais au-dessus du chat. Elle est active par défaut ; inAppNotificationsEnabled = false la désactive.

iOS (Swift)
Deskwoot.setLauncherVisible(true)            // show the round chat button
Deskwoot.inAppNotificationsEnabled = false   // no card for new replies
Android (Kotlin)
Deskwoot.setLauncherVisible(true)            // show the round chat button
Deskwoot.inAppNotificationsEnabled = false   // no card for new replies

Utilisateurs connectés

Sans identify, le visiteur discute de façon anonyme et la conversation reste sur ce téléphone. Quand votre utilisateur est connecté, identifiez-le : ses conversations le suivent alors sur chaque appareil et dans le chat de votre site sur la même boîte de réception, et votre équipe voit qui il est.

Deskwoot ne fait confiance à un utilisateur qu'avec identifierHash : le HMAC SHA256 de identifier avec le secret de signature de votre boîte de réception, en hexadécimal. Votre serveur le calcule et le transmet à l'application. C'est la même signature que sur le site, avec l'e-mail, le nom et les attributs signés en option : Vérification d'identité sur la page du widget.

iOS (Swift)
// After your own sign in, with the hash from your server
Deskwoot.identify(DeskwootUser(
    identifier: user.id,
    identifierHash: hashFromYourServer,
    email: user.email,   // optional
    name: user.name      // optional
))

// When the user signs out of your app
Deskwoot.logout()
Android (Kotlin)
// After your own sign in, with the hash from your server
Deskwoot.identify(
    DeskwootUser(
        identifier = user.id,
        identifierHash = hashFromYourServer,
        email = user.email,   // optional
        name = user.name,     // optional
    ),
)

// When the user signs out of your app
Deskwoot.logout()

Appelez identify à chaque démarrage de votre application dès qu'elle connaît son utilisateur, et de nouveau après une connexion. Sur Android, si votre application a enregistré l'utilisateur et le hash, appelez-le dans Application.onCreate juste après setup : Android peut démarrer votre application pour un appui sur une notification sans ouvrir aucun de vos écrans. Appelez logout() quand l'utilisateur se déconnecte, y compris à un démarrage où votre application ne retrouve plus sa session, et seulement dans ces cas : le SDK supprime ce qu'il gardait sur le visiteur, y compris le chat d'un visiteur qui ne s'est jamais connecté, et le prochain chat commence avec un nouveau visiteur anonyme.

Ne mettez jamais le secret de signature dans votre application. Quiconque décompresse l'application pourrait le lire et discuter au nom de n'importe lequel de vos utilisateurs.

Réponses non lues

unreadCount est le nombre de réponses que le visiteur n'a pas encore lues, sur toutes ses conversations, par exemple pour un badge sur votre bouton d'aide. Lisez-le une fois pour la première valeur : unreadCountDidChange sur iOS et un UnreadCountListener sur Android ne signalent que les changements.

iOS (Swift)
let count = Deskwoot.unreadCount

NotificationCenter.default.addObserver(
    forName: Deskwoot.unreadCountDidChange, object: nil, queue: .main
) { note in
    let count = note.userInfo?["count"] as? Int ?? 0
    // show count on your help button
}
Android (Kotlin)
val count = Deskwoot.unreadCount

val listener = UnreadCountListener { count ->
    badge.text = count.toString()
}
Deskwoot.addUnreadCountListener(listener)
// when the screen goes away
Deskwoot.removeUnreadCountListener(listener)

Langue et thème

Le chat parle la langue fixe de la boîte de réception si elle en a une. Sinon, il suit votre application : sur iOS la langue dans laquelle votre application tourne, sur Android la langue du téléphone ou celle que l'utilisateur a choisie pour votre application. Donnez à language une balise de langue comme "de" ou "pt-BR" pour la choisir vous-même à la place de celle de l'application ; elle vaut tant que l'application tourne et n'est jamais enregistrée. Une langue que le chat ne connaît pas devient l'anglais.

Le chat connaît les 10 langues visiteurs du chat de votre site : anglais, allemand (avec le du ou le Sie de la boîte de réception), espagnol, français, portugais du Brésil, arabe (de droite à gauche), hindi, italien, japonais et chinois simplifié. Chaque texte et chaque libellé pour lecteur d'écran est dans cette seule langue.

Les couleurs viennent de la couleur de marque de la boîte de réception, en une variante claire et une variante sombre. Par défaut, le chat suit votre application : clair ou sombre comme l'écran au-dessus duquel il s'ouvre. theme le règle sur system (par défaut), light, dark ou inbox (le réglage propre de la boîte de réception, comme sur le site).

iOS (Swift)
Deskwoot.language = "de"   // nil: the inbox's language, else your app's
Deskwoot.theme = .system   // .system (default), .light, .dark or .inbox
Android (Kotlin)
Deskwoot.language = "de"                 // null: the inbox's language, else your app's
Deskwoot.theme = Deskwoot.Theme.SYSTEM   // SYSTEM (default), LIGHT, DARK or INBOX

Le texte utilise la police du système et grandit avec la taille de texte du téléphone. Sur Android, si votre application ne garde que certaines langues (localeFilters), le chat ne peut utiliser que celles-ci.

Notifications push

Sans push, une réponse atteint le visiteur tant que votre application est ouverte : dans le compteur de réponses non lues, sur la carte et sur le badge du bouton du chat. Avec le push, elle l'atteint aussi quand l'application est fermée. Le SDK ne parle jamais lui-même à Apple ou à Google et n'embarque pas Firebase : votre application obtient son jeton d'appareil comme elle le fait déjà et le transmet au SDK. Il ne demande pas non plus l'autorisation des notifications ; votre application s'en charge au moment qui lui convient.

Dans Deskwoot

  1. Ouvrez Paramètres → Boîtes de réception → votre boîte de réception → Chat dans votre application iOS et Android pour la boîte de réception dont votre application utilise le jeton.
  2. Pour iOS : créez une clé d'authentification APNs dans votre compte Apple Developer, sous Keys. Collez-la ou importez-la dans Clé d'authentification APNs (.p8), puis saisissez son ID de clé, votre ID d'équipe et le Bundle ID de votre application.
  3. Pour Android : dans Firebase, ouvrez Paramètres du projet, puis Comptes de service, et générez une nouvelle clé privée. Collez ou importez ce fichier dans JSON du compte de service.
  4. Cliquez sur Enregistrer sous chaque bloc. Deskwoot vérifie la clé auprès d'Apple ou de Google avant de la garder, et le bloc affiche alors Connecté.

Dans votre application iOS

Activez la capability Push Notifications de la cible de votre application. Demandez l'autorisation et enregistrez votre application auprès d'Apple comme elle le fait pour ses propres notifications, puis transmettez le jeton d'appareil à setPushToken à chaque démarrage. Dans le délégué du notification center, laissez le SDK gérer ses propres notifications :

iOS (Swift)
import Deskwoot
import UIKit
import UserNotifications

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Deskwoot.setup(widgetToken: "YOUR_WIDGET_TOKEN")
        UNUserNotificationCenter.current().delegate = self
        // Ask for permission when it suits your app, then:
        application.registerForRemoteNotifications()
        return true
    }

    func application(
        _ application: UIApplication,
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
    ) {
        Deskwoot.setPushToken(deviceToken)
    }
}

// The system calls both on the main thread. Written this way they
// compile in the Swift 5 and the Swift 6 language mode.
extension AppDelegate: UNUserNotificationCenterDelegate {
    // A notification while your app is in front
    nonisolated func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        willPresent notification: UNNotification,
        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
    ) {
        MainActor.assumeIsolated {
            if let options = Deskwoot.presentationOptions(for: notification) {
                completionHandler(options)
            } else {
                completionHandler([.banner, .list, .sound])   // one of your own
            }
        }
    }

    // A tap on a notification
    nonisolated func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse,
        withCompletionHandler completionHandler: @escaping () -> Void
    ) {
        MainActor.assumeIsolated {
            if !Deskwoot.handleNotificationResponse(response) {
                // one of your own: handle it here
            }
            completionHandler()
        }
    }
}

presentationOptions(for:) répond nil pour une notification qui ne vient pas de Deskwoot. Pour une notification Deskwoot, il n'affiche aucune bannière tant que le visiteur regarde cette conversation. handleNotificationResponse ouvre la conversation et répond true ; pour vos propres notifications, il répond false. isDeskwootNotification(_:) distingue les deux partout ailleurs. Le SDK détecte lui-même si un jeton appartient au sandbox d'Apple ou à la production.

Dans une application SwiftUI, branchez ce délégué d'application avec @UIApplicationDelegateAdaptor. Le SDK ne fait de swizzling sur aucune méthode : votre application fait ces appels elle-même.

Dans votre application Android

Votre application a besoin de Firebase Cloud Messaging. Transmettez le jeton d'enregistrement FCM à setPushToken une fois au démarrage et dans onNewToken, et passez les messages de Deskwoot dans onMessageReceived :

Android (Kotlin)
class PushService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        Deskwoot.setPushToken(token)
    }

    override fun onMessageReceived(message: RemoteMessage) {
        if (Deskwoot.isDeskwootPush(message.data)) {
            Deskwoot.handlePush(this, message.data)
            return
        }
        // one of your own: handle it here
    }
}

// Once at start, for example in Application.onCreate after Deskwoot.setup
FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
    Deskwoot.setPushToken(token)
}

Le SDK dessine lui-même la notification, dans son propre canal de notification et avec l'icône de votre application (setNotificationIcon(resId) en définit une autre). Un appui ouvre la conversation, et rien ne s'affiche tant que le visiteur regarde cette conversation. À partir d'Android 13, votre application demande POST_NOTIFICATIONS au moment qui lui convient ; sans cette autorisation, aucune notification ne s'affiche.

Quand un push part

Deskwoot en envoie un pour chaque réponse de votre équipe ou de votre bot IA, jamais pour les messages du visiteur lui-même. Si le visiteur était en ligne un instant plus tôt, Deskwoot attend 12 secondes et n'envoie rien s'il a lu la réponse entre-temps. Le titre indique qui a écrit, et le texte montre jusqu'à 160 caractères de la réponse. Quand votre utilisateur se déconnecte, le SDK retire les notifications de ce visiteur et désinscrit le téléphone de ses notifications push.

Ce que le SDK ajoute à votre application

QuoiiOSAndroid
TailleEnviron 1,24 MB compressé (l'application zippée, proche de ce que livre l'App Store). Sans compression, 2,67 MB de code et 0,17 MB de textes en 10 langues.Environ 0,7 MB avec tout ce qu'il apporte : une application minimale compilée avec R8 passe de 23 KB à 724 KB. Une application qui embarque déjà Kotlin, les coroutines et androidx paie moins. L'AAR lui-même fait 1,7 MB.
AutorisationsAucune. Ajoutez NSCameraUsageDescription seulement si les visiteurs peuvent envoyer des photos prises avec l'appareil photo ; sans cette clé, le menu des pièces jointes propose la photothèque et les fichiers, qui ne demandent aucune autorisation.Seulement INTERNET. Les photos viennent du sélecteur de photos du système et les fichiers du sélecteur de documents du système ; aucun des deux ne demande d'autorisation. L'appareil photo passe par l'application Appareil photo du système, et le SDK ne demande l'autorisation de l'appareil photo que si votre application la déclare elle-même.
DépendancesAucune en dehors des frameworks d'Apple.kotlinx-coroutines-android, androidx.annotation, androidx.core, androidx.activity, androidx.recyclerview, avec ce qu'elles apportent elles-mêmes (androidx lifecycle, savedstate, collection et autres), mais sans androidx.profileinstaller. Pas d'OkHttp, pas de Retrofit, pas de bibliothèque JSON ni d'images, pas de Firebase, pas de Compose.
Dans votre applicationRien ne s'exécute avant setup, et le SDK ne fait de swizzling sur aucune méthode.1 Activity (DeskwootActivity) et 1 FileProvider (DeskwootFileProvider), tous deux non exportés. Aucun service et aucun receiver. Avant setup, le SDK garde seulement le contexte de votre application dans son FileProvider, et aucun de vos thèmes ou styles n'est modifié.
Au démarrageAucun coût : setup fait chaque étape disque et réseau en arrière-plan.Aucun coût : setup fait chaque étape disque et réseau en arrière-plan.

Mesuré pour la version 1.0.0. iOS : deux applications vides qui ne diffèrent que par le SDK, build Release pour iPhone (arm64) ; le binaire allégé fait 2 744 720 octets contre 73 248 octets sans le SDK. Android : une application minimale avec 1 Activity.

Questions fréquentes

Voici les réponses courtes. Pour tout le reste, demandez à Fynn ci-dessous.

Existe-t-il un SDK pour React Native ou Flutter ?

Non. Deskwoot propose des SDK natifs pour iOS (Swift) et Android (Kotlin et Java), et aucun paquet pour React Native ou Flutter. Dans une application construite avec eux, vous pouvez afficher le chat du site dans une web view avec le mode intégré du widget, décrit sur la page du SDK du widget.

Le chat fonctionne-t-il sans notifications push ?

Oui. Tant que votre application est ouverte, une réponse apparaît dans le compteur de réponses non lues, sur la carte en bas de votre application et sur le badge du bouton du chat. Les notifications push ajoutent les réponses qui arrivent quand l'application est fermée.

Où arrivent les conversations de l'application ?

Dans la boîte de réception dont vous passez le jeton du widget à setup. Avec le même jeton que votre site, les chats de l'application et ceux du site partagent une boîte de réception, ses réglages, votre équipe et votre bot IA.

Démo interactive de Deskwoot