Chat-SDK für iOS und Android

Bring deinen Deskwoot-Live-Chat als native Ansicht in deine eigene App für iOS oder Android. Dein Team und dein KI-Bot antworten in Deskwoot, wie im Chat auf deiner Website.

Auf dieser Seite

Was das SDK ist

Das SDK bringt den Chat deines Website-Posteingangs als native Ansicht in deine App. Gezeichnet wird er mit UIKit auf iOS und mit den eigenen Views von Android auf Android, nicht als Webseite geladen; nur der Text eines Hilfeartikels erscheint in einer Web View des Systems. Besucher schreiben deinem Team und deinem KI-Bot, durchsuchen dein Hilfecenter und lesen die Antworten direkt in deiner App.

Es ist derselbe Chat wie auf deiner Website. Er liest dieselben Einstellungen des Posteingangs (Markenfarbe, Texte, Team, KI-Bot, Hilfecenter) und zeigt das Design, das du für den Posteingang gewählt hast: Klartext, Empfang oder Direkt. Er spricht die 10 Besuchersprachen des Website-Chats.

Konversationen aus der App landen in diesem Posteingang, wo dein Team sie wie gewohnt beantwortet.

Voraussetzungen

PlattformLäuft aufGebaut mit
iOSiOS 15 oder neuer, iPhone und iPadXcode 15 oder neuer (Swift 5.9)
AndroidAndroid 5.0 (API 21) oder neuercompileSdk 34 oder höher, Android Gradle Plugin 8 oder neuer, Kotlin 1.9 oder neuer oder Java. Apps mit Views und Apps mit Jetpack Compose funktionieren beide.

Außerdem brauchst du einen Deskwoot-Posteingang vom Typ Live-Chat (den Website-Chat). Das SDK nutzt seinen Widget-Token.

Installation

iOS: Wähle in Xcode File → Add Package Dependencies, gib https://github.com/Deskwoot/deskwoot-ios ein und füge die Bibliothek Deskwoot zum Target deiner App hinzu. Oder trag das Paket in deine Package.swift ein:

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: Das SDK liegt auf Maven Central. Füge es zur build.gradle.kts deines App-Moduls hinzu:

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

Das iOS-Paket kommt als Quellcode und wird mit deinem Xcode gebaut. Die Android-Bibliothek funktioniert mit Kotlin und mit Java.

Einrichtung

Das SDK braucht den Widget-Token eines Posteingangs vom Typ Live-Chat. Öffne in Deskwoot Einstellungen → Posteingänge → dein Posteingang → Chat in deiner iOS- und Android-App: Oben steht der Token zum Kopieren.

Ruf setup einmal mit diesem Token auf, so früh du willst: auf iOS in application(_:didFinishLaunchingWithOptions:), auf Android in Application.onCreate. Speicher und Netzwerk nutzt es nie auf dem Main Thread, und ein zweiter Aufruf mit demselben Token tut nichts.

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")
    }
}

Auf iOS rufst du das SDK auf dem Main Thread auf (ein Aufruf aus einem anderen Thread wird protokolliert und läuft einen Moment später auf dem Main Thread). Auf Android funktioniert jeder Aufruf aus jedem Thread.

Ein widgetToken = ein Posteingang. Mit dem Token deiner Website landen die Chats aus der App im selben Posteingang wie die Chats von der Website. Mit dem Token eines zweiten Live-Chat-Posteingangs hältst du sie getrennt.

Chat öffnen

Öffne den Chat über deinen eigenen Hilfe-Button. Jeder Aufruf funktioniert direkt nach setup, auch bevor die Einstellungen des Posteingangs geladen sind.

iOSAndroidWas sich öffnet
present()present(activity)Die Startseite.
presentConversation()presentConversation(activity)Die neueste laufende Konversation des Besuchers oder eine neue.
presentNewConversation(text:)presentNewConversation(activity, text)Eine neue Konversation mit deinem Text im Nachrichtenfeld. Der Besucher kann ihn ändern und schickt ihn selbst ab; das SDK sendet nichts für ihn.
presentHelpCenter()presentHelpCenter(activity)Das Hilfecenter oder die Startseite, wenn der Posteingang keins hat.
dismiss()dismiss()Schließt den Chat, wenn er offen ist.

Auf iOS öffnet sich der Chat als Sheet über dem obersten Bildschirm deiner App; mit from: wählst du den Bildschirm. Auf Android öffnet er sich als eigene Activity; übergib die Activity, aus der du aufrufst, dann bleibt der Chat im Task deiner App und übernimmt von ihr den hellen oder dunklen Modus.

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()

Der Launcher

setLauncherVisible(true) zeigt den runden Chat-Button des Website-Widgets über den Inhalten deiner App: in deiner Markenfarbe, auf der Seite, die für den Posteingang eingestellt ist, mit einem Badge für ungelesene Antworten. Ein Tipp öffnet den Chat. Standardmäßig ist er ausgeblendet, weil die meisten Apps den Chat über einen eigenen Button öffnen.

Eine Antwort bei geschlossenem Chat

Kommt eine Antwort, während deine App offen und der Chat geschlossen ist, gleitet unten in deiner App eine kleine Karte hoch: mit Bild und Namen der Person, die geschrieben hat, und 2 Zeilen der Antwort. Ein Tipp öffnet diese Konversation. Die Karte braucht keine Berechtigung und erscheint nie über dem Chat selbst. Sie ist standardmäßig an; inAppNotificationsEnabled = false schaltet sie aus.

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

Angemeldete Nutzer

Ohne identify chattet ein Besucher anonym, und die Konversation bleibt auf diesem Handy. Ist dein Nutzer angemeldet, identifiziere ihn: Dann folgen ihm seine Konversationen auf jedes Gerät und in den Website-Chat desselben Posteingangs, und dein Team sieht, wer er ist.

Deskwoot vertraut einem Nutzer nur mit identifierHash: dem HMAC SHA256 von identifier mit dem Signatur-Geheimnis deines Posteingangs, als Hex. Dein Server berechnet ihn und gibt ihn an die App. Es ist dieselbe Signatur wie auf der Website, mit optionaler E-Mail, Namen und signierten Attributen: Nutzer-Verifizierung auf der Widget-Seite.

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()

Ruf identify bei jedem Start deiner App auf, sobald sie ihren Nutzer kennt, und noch einmal nach einer Anmeldung. Auf Android gilt: Hat deine App den Nutzer und den Hash gespeichert, ruf es in Application.onCreate direkt nach setup auf, denn Android kann deine App für einen Tipp auf eine Benachrichtigung starten, ohne einen deiner Bildschirme zu öffnen. Ruf logout() auf, wenn sich der Nutzer abmeldet, auch bei einem Start, bei dem deine App seine Sitzung nicht mehr vorfindet, und nur dann: Das SDK löscht, was es über den Besucher gespeichert hat, auch den Chat eines Besuchers, der nie angemeldet war, und der nächste Chat beginnt mit einem neuen, anonymen Besucher.

Leg das Signatur-Geheimnis nie in deine App. Wer die App entpackt, könnte es lesen und als jeder deiner Nutzer chatten.

Ungelesene Antworten

unreadCount ist die Zahl der Antworten, die der Besucher noch nicht gelesen hat, über alle seine Konversationen, zum Beispiel für ein Badge an deinem Hilfe-Button. Lies den Wert einmal für den Anfang: unreadCountDidChange auf iOS und ein UnreadCountListener auf Android melden nur Änderungen.

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)

Sprache und Design

Der Chat spricht die feste Sprache des Posteingangs, wenn er eine hat. Sonst folgt er deiner App: auf iOS der Sprache, in der deine App läuft, auf Android der Sprache des Handys oder der, die der Nutzer für deine App gewählt hat. Setz language auf ein Sprach-Tag wie "de" oder "pt-BR", um sie statt der App-Sprache selbst zu wählen; das gilt, solange die App läuft, und wird nie gespeichert. Eine Sprache, die der Chat nicht kennt, wird zu Englisch.

Der Chat kennt die 10 Besuchersprachen des Website-Chats: Englisch, Deutsch (mit dem Du oder Sie des Posteingangs), Spanisch, Französisch, brasilianisches Portugiesisch, Arabisch (von rechts nach links), Hindi, Italienisch, Japanisch und vereinfachtes Chinesisch. Jeder Text und jedes Label für Screenreader ist in dieser einen Sprache.

Die Farben kommen aus der Markenfarbe des Posteingangs, in einer hellen und einer dunklen Variante. Standardmäßig folgt der Chat deiner App: hell oder dunkel wie der Bildschirm, über dem er sich öffnet. theme stellt system (Standard), light, dark oder inbox ein (die eigene Einstellung des Posteingangs, wie auf der Website).

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

Der Text nutzt die Systemschrift und wächst mit der Textgröße des Handys. Behält deine Android-App nur einige Sprachen (localeFilters), kann der Chat nur diese nutzen.

Push-Benachrichtigungen

Ohne Push erreicht eine Antwort den Besucher, solange deine App offen ist: im Zähler der ungelesenen Antworten, auf der Karte und am Badge des Launchers. Mit Push erreicht sie ihn auch bei geschlossener App. Das SDK spricht nie selbst mit Apple oder Google und bringt kein Firebase mit: Deine App holt sich ihren Geräte-Token wie bisher und gibt ihn an das SDK. Nach der Erlaubnis für Benachrichtigungen fragt es auch nicht; das macht deine App, wann es passt.

In Deskwoot

  1. Öffne Einstellungen → Posteingänge → dein Posteingang → Chat in deiner iOS- und Android-App für den Posteingang, dessen Token deine App nutzt.
  2. Für iOS: Erstelle in deinem Apple-Developer-Konto unter Keys einen APNs-Schlüssel. Füg ihn bei APNs-Schlüssel (.p8) ein oder lade die Datei hoch und trag dann seine Schlüssel-ID, deine Team-ID und die Bundle-ID deiner App ein.
  3. Für Android: Öffne in Firebase die Projekteinstellungen, dann Dienstkonten, und erzeuge einen neuen privaten Schlüssel. Füg diese Datei bei JSON des Dienstkontos ein oder lade sie hoch.
  4. Klick unter jedem Block auf Speichern. Deskwoot prüft den Schlüssel bei Apple oder Google, bevor es ihn behält, und der Block zeigt dann Verbunden.

In deiner iOS-App

Schalte die Capability Push Notifications für das Target deiner App ein. Frag nach der Erlaubnis und registriere dich bei Apple, wie deine App es für ihre eigenen Benachrichtigungen tut, und gib den Geräte-Token bei jedem Start an setPushToken. Lass in deinem Delegate des Notification Center das SDK seine eigenen Benachrichtigungen übernehmen:

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:) antwortet nil für eine Benachrichtigung, die nicht von Deskwoot ist. Für eine von Deskwoot zeigt es kein Banner, solange der Besucher diese Konversation ansieht. handleNotificationResponse öffnet die Konversation und antwortet true; für deine eigenen Benachrichtigungen antwortet es false. isDeskwootNotification(_:) unterscheidet die beiden an jeder anderen Stelle. Ob ein Token zur Sandbox von Apple oder zur Produktion gehört, erkennt das SDK selbst.

In einer SwiftUI-App hängst du diesen App-Delegate mit @UIApplicationDelegateAdaptor an. Das SDK swizzlet keine Methoden: Deine App macht diese Aufrufe selbst.

In deiner Android-App

Deine App braucht Firebase Cloud Messaging. Gib den FCM-Registrierungstoken einmal beim Start und in onNewToken an setPushToken und reich die Nachrichten von Deskwoot in onMessageReceived weiter:

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)
}

Das SDK zeichnet die Benachrichtigung selbst, in einem eigenen Benachrichtigungskanal und mit dem Icon deiner App (setNotificationIcon(resId) setzt ein anderes). Ein Tipp öffnet die Konversation, und solange der Besucher diese Konversation ansieht, erscheint nichts. Ab Android 13 fragt deine App nach POST_NOTIFICATIONS, wann es passt; ohne diese Erlaubnis erscheint keine Benachrichtigung.

Wann ein Push rausgeht

Deskwoot schickt einen für jede Antwort deines Teams oder deines KI-Bots, nie für die eigenen Nachrichten des Besuchers. War der Besucher kurz vorher online, wartet Deskwoot 12 Sekunden und schickt nichts, wenn er die Antwort bis dahin gelesen hat. Der Titel nennt, wer geschrieben hat, und der Text zeigt bis zu 160 Zeichen der Antwort. Meldet sich dein Nutzer ab, entfernt das SDK die Benachrichtigungen dieses Besuchers und meldet das Handy von seinen Pushes ab.

Was das SDK deiner App hinzufügt

WasiOSAndroid
GrößeRund 1,24 MB komprimiert (die App gezippt, nah an dem, was der App Store ausliefert). Unkomprimiert 2,67 MB Code und 0,17 MB Texte in 10 Sprachen.Rund 0,7 MB mit allem, was es mitbringt: Eine minimale App, mit R8 gebaut, wächst von 23 KB auf 724 KB. Eine App, die Kotlin, Coroutines und androidx schon mitbringt, zahlt weniger. Das AAR selbst hat 1,7 MB.
BerechtigungenKeine. Trag NSCameraUsageDescription nur ein, wenn Besucher mit der Kamera aufgenommene Fotos schicken dürfen; ohne den Eintrag bietet das Anhangmenü die Fotomediathek und Dateien, die keine Berechtigung brauchen.Nur INTERNET. Fotos kommen aus der Fotoauswahl des Systems, Dateien aus der Dateiauswahl des Systems, und beide brauchen keine Berechtigung. Die Kamera läuft über die Kamera-App des Systems, und nach der Kamera-Berechtigung fragt das SDK nur, wenn deine App sie selbst deklariert.
AbhängigkeitenKeine außer den Frameworks von Apple.kotlinx-coroutines-android, androidx.annotation, androidx.core, androidx.activity, androidx.recyclerview, mit dem, was diese selbst mitbringen (androidx lifecycle, savedstate, collection und ähnliche), aber ohne androidx.profileinstaller. Kein OkHttp, kein Retrofit, keine Bibliothek für JSON oder Bilder, kein Firebase, kein Compose.
In deiner AppVor setup läuft nichts, und das SDK swizzlet keine Methoden.1 Activity (DeskwootActivity) und 1 FileProvider (DeskwootFileProvider), beide nicht exportiert. Kein Service und kein Receiver. Vor setup merkt sich das SDK nur den Kontext deiner App in seinem FileProvider, und keins deiner Themes oder Styles wird geändert.
Beim App-StartKeine Kosten: setup erledigt jeden Schritt mit Speicher und Netzwerk im Hintergrund.Keine Kosten: setup erledigt jeden Schritt mit Speicher und Netzwerk im Hintergrund.

Gemessen für Version 1.0.0. iOS: zwei sonst leere Apps, die sich nur durch das SDK unterscheiden, Release-Build für iPhone (arm64); die gestrippte Binärdatei hat 2.744.720 Bytes gegenüber 73.248 Bytes ohne SDK. Android: eine minimale App mit 1 Activity.

Häufig gestellte Fragen

Die kurzen Antworten stehen hier. Für alles andere frag unten Fynn.

Gibt es ein SDK für React Native oder Flutter?

Nein. Deskwoot hat native SDKs für iOS (Swift) und Android (Kotlin und Java) und kein Paket für React Native oder Flutter. In einer App, die damit gebaut ist, kannst du den Website-Chat mit dem Embedded-Modus des Widgets in einer Web View zeigen; die Seite zum Widget-SDK beschreibt ihn.

Funktioniert der Chat ohne Push-Benachrichtigungen?

Ja. Solange deine App offen ist, zeigt sich eine Antwort im Zähler der ungelesenen Antworten, auf der Karte unten in deiner App und am Badge des Launchers. Push-Benachrichtigungen bringen dazu die Antworten, die bei geschlossener App kommen.

Wo landen die Konversationen aus der App?

In dem Posteingang, dessen Widget-Token du an setup gibst. Mit demselben Token wie deine Website teilen sich Chats aus der App und von der Website einen Posteingang, seine Einstellungen, dein Team und deinen KI-Bot.

Interaktive Deskwoot-Demo