Hodhod Android SDK Tutorial: nativer In-App-Support in 10 Minuten

Sie haben eine Android-App, und Ihre Kunden stellen ihre Fragen direkt darin. Am einfachsten öffnen Sie dafür das Web-Widget in einer WebView. Wenn Ihnen aber eine native Optik, die Android-Tastatur, die Auswahl von Anhängen und das Gefühl einer echten App wichtig sind, erledigt das Hodhod Android SDK dieselbe Aufgabe ohne WebView. Es spricht mit demselben Posteingang und derselben Widget-API wie das Web-Widget, sodass Gespräche und Tickets aus der App im selben gemeinsamen Team-Posteingang landen.

In diesem Tutorial binden wir eine Kotlin-App Schritt für Schritt an das SDK an: Installation, Konfiguration, Chat öffnen, Nutzer identifizieren, Design und Sprache sowie der Zähler für ungelesene Nachrichten. Am Ende sehen Sie, wie sich Tickets und die Zufriedenheitsumfrage verhalten und wie Sie häufige Fehler beheben.

Die aktuelle SDK-Version ist eine Beta (1.0.0-beta04). Die unten genannten Klassennamen und Parameter stammen aus dieser Version und können sich bis zur stabilen Version ändern.

SDK oder Web-Widget in einer WebView?

Wenn Ihre App nur eine Webseite in einer Android-Hülle ist, genügt das Web-Widget. Ist Ihre App nativ und gehört der Support zu ihrem Erlebnis, ist das SDK die bessere Wahl.

Was das SDK enthält

• Kontaktmodi des Posteingangs: Live-Chat, Ticket, beides oder „Ticket bei Abwesenheit“. Die Einstellung, die Sie im Panel für das Web-Widget gewählt haben, gilt auch in der App.
• Tickets: ein Ticketformular mit Betreff, Beschreibung, Kategorie und Anhängen (wie im Posteingang konfiguriert), eine Liste „Meine Tickets“ und der Verlauf jedes Tickets mit Statusanzeige und Antworten.
• Zufriedenheitsumfrage (CSAT): drei Darstellungsformen, Emojis, Sterne und Zahlen von 1 bis 5, mit optionalem Kommentarfeld.
• Ankündigungen und Warnungen des Posteingangs (seit 1.0.0-beta04): Dieselben Ankündigungen wie im Web-Widget erscheinen oben auf dem Startbildschirm, ganz ohne zusätzlichen Code.
• Pre-Chat-Formular, Öffnungszeiten und Feiertage, das Störungshinweis-Banner, das Beenden eines Gesprächs und der E-Mail-Versand des Verlaufs, wie im Web-Widget.
• Sechs Sprachen: Persisch, Englisch, Arabisch, Deutsch, Spanisch und Französisch. Andere Sprachen fallen auf Englisch zurück.
• Helles und dunkles Design, die Markenfarbe des Posteingangs und eine manuelle Farbüberschreibung.
• Verbindungsabbruch: Bricht das Netzwerk oder der WebSocket ab, erscheint ein Banner „Keine Verbindung“, das SDK verbindet sich selbstständig neu, und eine Nachricht, die nicht gesendet werden konnte, bleibt mit einer Schaltfläche „Erneut versuchen“ erhalten.

Voraussetzungen

• Ein Posteingang vom Typ „Webseite“ im Hodhod-Panel. Haben Sie noch keinen, folgen Sie der Anleitung zur Live-Chat-Installation bis zum Anlegen des Posteingangs.
• Das websiteToken des Posteingangs. Derselbe Wert steht im Widget-Code-Schnipsel.
• minSdk 24 oder höher, Kotlin und Java 17. Das SDK wird mit compileSdk 35 gebaut, und seine Oberfläche basiert auf Jetpack Compose. Verwendet Ihre App noch Views, rufen Sie Hodhod.open auf, um die fertige Activity zu nutzen; die Compose-Abhängigkeiten werden automatisch hinzugefügt.

Schritt 1: Abhängigkeit hinzufügen

Das SDK besteht aus zwei Modulen: hodhod-core (ohne Oberfläche: API, Live-Verbindung und Logik) und hodhod-ui (die Compose-Oberfläche und eine fertige Activity). hodhod-ui zieht hodhod-core nach sich, für die fertige Oberfläche genügt also dieses eine Modul.

Das SDK ist Open Source (MIT) unter github.com/HodHodChat/hodhod-android-sdk und wird über JitPack installiert, das es aus dem Git-Tag 1.0.0-beta04 des Repositorys baut. Fügen Sie zuerst das JitPack-Repository in settings.gradle.kts ein:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

Fügen Sie dann die Abhängigkeit hinzu:

// app/build.gradle.kts
dependencies {
    implementation("com.github.HodHodChat.hodhod-android-sdk:hodhod-ui:1.0.0-beta04")
}

Die Koordinaten lauten com.github.HodHodChat.hodhod-android-sdk:hodhod-ui:1.0.0-beta04 (und ...:hodhod-core:1.0.0-beta04, wenn Sie nur den Core ohne Oberfläche brauchen). Die Kotlin-Paketnamen in Ihrem Code bleiben chat.hodhod.sdk.

Schritt 2: In der Application-Klasse konfigurieren

Konfigurieren Sie das SDK einmal in Application.onCreate. Solange weder Hodhod.start(), Hodhod.open() noch Hodhod.identify() aufgerufen wurde, sendet das SDK keine Netzwerkanfragen.

import android.app.Application
import chat.hodhod.sdk.Hodhod
import chat.hodhod.sdk.HodhodConfig

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Hodhod.configure(
            this,
            HodhodConfig(
                baseUrl = "https://hodhod.chat",          // Ihr Hodhod-Server, ohne zusätzlichen Pfad
                websiteToken = "YOUR_WEBSITE_TOKEN",      // das Token des Website-Posteingangs
            ),
        )
        Hodhod.start() // optional: damit der Zähler für ungelesene Nachrichten schon vor dem Öffnen des Chats funktioniert
    }
}

Tragen Sie die Klasse in AndroidManifest.xml mit android:name=".MyApp" im <application>-Tag ein. Die Basis-URL muss https:// verwenden; die einzige Ausnahme ist ein lokaler Server in Debug-Builds, der unter „Fehlerbehebung“ behandelt wird.

Schritt 3: Den Chat öffnen

Es gibt vier Wege, beginnend mit dem einfachsten.

1. Die fertige Activity. Eine Zeile aus jeder Activity oder jedem Fragment:

Hodhod.open(context)

Das öffnet HodhodChatActivity: eine Vollbildseite mit einem vom Design Ihrer App getrennten Theme, die den Zurück-Button selbst behandelt. Dieselbe Seite öffnet sich auch über den Deep Link hodhod://chat.

2. In den eigenen Compose-Screen einbetten. Wenn der Chat in der Navigation Ihrer App liegen soll:

@Composable
fun SupportScreen(onBack: () -> Unit) {
    HodhodChat(modifier = Modifier.fillMaxSize(), onClose = onBack)
}

HodhodChat zeigt je nach Einstellungen des Posteingangs den Startbildschirm, den Chat, die Tickets und das Pre-Chat-Formular und ruft onClose auf, wenn der Nutzer den ersten Bildschirm verlässt oder auf die Schaltfläche zum Schließen tippt. Wenn Sie Statusleiste und Navigationsleiste berücksichtigen müssen, behandeln Sie die Insets in modifier; HodhodChatActivity macht das mit windowInsetsPadding(WindowInsets.systemBars).

3. Ein schwebender Button mit Badge für ungelesene Nachrichten. HodhodBubble ist ein runder Button, der die Zahl der ungelesenen Nachrichten anzeigt und beim Klick Hodhod.open aufruft:

Box(Modifier.fillMaxSize()) {
    // Inhalt des Bildschirms
    HodhodBubble(Modifier.align(Alignment.BottomEnd).padding(16.dp))
}

Übergeben Sie onClick für ein anderes Verhalten. Die Farbe des Buttons stammt aus dem Posteingang, oder Sie ändern sie mit dem Parameter accent.

4. Ein eigener Button. Jeder Button im Design Ihrer App, etwa „Support“ im Profilbildschirm, ruft einfach Hodhod.open(context) auf.

Schritt 4: Den Nutzer identifizieren

Ist der Nutzer in Ihrer App angemeldet, stellen Sie ihn Hodhod vor, damit Gespräche und Tickets unter seinem Namen gespeichert werden und auch auf einem anderen Gerät auffindbar sind:

Hodhod.identify(
    HodhodUser(
        identifier = user.id,                // eine stabile Nutzer-ID in Ihrem System
        identifierHash = hashFromBackend,    // HMAC, auf Ihrem Backend berechnet
        name = user.name,
        email = user.email,
        phone = user.phone,
        customAttributes = mapOf("plan" to "pro"),
    )
) { result ->
    result.onFailure { Log.w("Support", "identify failed: ${it.message}") }
}

Ohne identifier ist der Nutzer ein anonymer Kontakt. Das Ergebnis wird im Main-Thread geliefert.

Warum identifierHash, und warum im Backend?

Könnte jeder die Kennung einer anderen Person senden, könnte er deren Gespräche lesen. Um das zu verhindern, hält Hodhod für jeden Posteingang einen geheimen HMAC-Schlüssel bereit (in den Einstellungen des Posteingangs unter „Identity Validation“) und prüft identifierHash so: ein HMAC mit SHA-256 über den identifier mit diesem Schlüssel, als Hex-String.

Der Schlüssel darf niemals in der App liegen. Nach der Anmeldung des Nutzers erhält die App nur den Wert identifierHash von Ihrem eigenen Backend. Zwei Beispiele:

// Node.js
import { createHmac } from 'node:crypto';

const identifierHash = createHmac('sha256', process.env.HODHOD_HMAC_KEY)
  .update(String(user.id))
  .digest('hex');

# Python
import hashlib, hmac, os

identifier_hash = hmac.new(
    os.environ["HODHOD_HMAC_KEY"].encode(),
    str(user.id).encode(),
    hashlib.sha256,
).hexdigest()

In PHP geht es genauso: hash_hmac('sha256', (string) $user->id, $key). Der identifier-String muss in der App und im Backend exakt derselbe sein.

Wenn Sie in den Einstellungen des Posteingangs „Require identity validation for all conversations“ aktivieren, werden Anfragen ohne identifierHash abgelehnt. Wir empfehlen, die Option einzuschalten, damit niemand durch Raten einer Kennung an fremde Gespräche gelangt.

Benutzerdefinierte Attribute und Abmeldung

Senden Sie benutzerdefinierte Attribute (zum Beispiel die App-Version oder den Tarif) mit HodhodUser oder separat. Sie werden in eine Warteschlange gestellt, bis die Sitzung existiert:

Hodhod.setCustomAttributes(mapOf("app_version" to BuildConfig.VERSION_NAME))

Wenn sich der Nutzer in Ihrer App abmeldet:

Hodhod.logout()

Das löscht die gespeicherte Sitzung und die Tokens und schließt die Verbindung; bei der nächsten Nutzung wird ein neuer anonymer Kontakt angelegt. So sieht die nächste Person, die sich auf demselben Telefon anmeldet, die Gespräche des vorherigen Nutzers nicht.

Schritt 5: Design, Sprache und Dunkelmodus

All das legen Sie in HodhodConfig fest:

HodhodConfig(
    baseUrl = "https://hodhod.chat",
    websiteToken = "YOUR_WEBSITE_TOKEN",
    locale = "fa",                       // fa, en, ar, de, es oder fr
    darkMode = DarkMode.AUTO,            // AUTO (System), LIGHT oder DARK
    accentColorOverride = 0xFF6A2BC4,    // eine ARGB-Farbe statt der Widget-Farbe des Posteingangs
)

• Sprache: locale in der Konfiguration hat Vorrang, danach die Kontosprache auf dem Server, danach die Gerätesprache. Eine nicht unterstützte Sprache fällt auf Englisch zurück. Die Schreibrichtung (RTL für Persisch und Arabisch) wird automatisch gesetzt.
• Design: AUTO folgt der Systemeinstellung.
• Farbe: Übergeben Sie accentColorOverride nicht, wird die Widget-Farbe verwendet, die Sie im Panel für den Posteingang festgelegt haben.

Schritt 6: Der Zähler für ungelesene Nachrichten

Die Zahl der ungelesenen Nachrichten ist ein StateFlow<Int>. Sie bleibt bei null, bis Hodhod.start() oder Hodhod.open() aufgerufen wurde; deshalb haben wir in Schritt 2 start() ergänzt. Der Zähler aktualisiert sich live, solange Ihre App läuft.

val unread by Hodhod.unreadCount.collectAsState()

BadgedBox(badge = { if (unread > 0) Badge { Text("$unread") } }) {
    Icon(Icons.Outlined.SupportAgent, contentDescription = "Support")
}

Wenn Sie HodhodBubble verwenden, zeigt der Button diesen Zähler selbst an. Der Ladezustand der Einstellungen steht in Hodhod.state (Idle, Loading, Ready oder Failed).

Wie sich Tickets und Umfrage in der App verhalten

Dieses Verhalten steuern die Einstellungen des Posteingangs im Panel; Code ist dafür nicht nötig:

• Kontaktmodus: Im Modus „Chat“ gelangt der Kunde direkt in ein Gespräch, im Modus „Ticket“ sieht er das Ticketformular, bei „beides“ wählt er selbst. Bei „Ticket bei Abwesenheit“ wird der Live-Chat gezeigt, solange das Team arbeitet, und außerhalb der Öffnungszeiten öffnet sich das Ticketformular. Dieser Modus hängt von den im Posteingang festgelegten Öffnungszeiten ab.
• Tickets: Nach dem Absenden wird die Ticketnummer angezeigt, und unter „Meine Tickets“ sieht der Kunde den Status (offen, in Bearbeitung, wartet auf Sie, gelöst, geschlossen) und antwortet im selben Verlauf. Zum Unterschied zwischen Tickets und Chat lesen Sie unseren Artikel zu Ticketsystem und Live-Chat im Vergleich.
• Umfrage: Nach dem Ende eines Gesprächs erscheint, wenn die Umfrage des Posteingangs aktiv ist, eine Bewertungskarte von 1 bis 5 in der für den Posteingang festgelegten Darstellung (Emojis, Sterne oder Zahlen). Wenn Ihnen das Ergebnis wichtig ist, lesen Sie was CSAT ist.
• Nach dem Ende eines Gesprächs: Der Kunde kehrt zum Startbildschirm zurück und kann je nach Kontaktmodus einen neuen Chat oder ein neues Ticket öffnen.
• Pre-Chat-Formular: Ist es für den Posteingang aktiviert, wird es vor dem ersten Gespräch angezeigt. Siehe das Pre-Chat-Formular.

Chatbot-Flows

Chatbot-Flows laufen im Android SDK nativ, ganz ohne Code auf Ihrer Seite. Hat der Posteingang einen aktiven Flow, zeigt die App ihn auf dem Startbildschirm: alle 17 Knotentypen, Variablen und Bedingungen, Eingabeprüfung und Bewertungen. Der Besucher kann an einen Live-Mitarbeiter oder als Ticket übergeben werden, und es werden dieselben Flow-Analysen wie im Web-Widget erfasst. Ist die Flow-Option require_flow aktiv, bleibt die direkte Karte „Unterhaltung starten“ verborgen, solange der Flow verfügbar ist (sie kehrt zurück, wenn der Flow nicht geladen werden kann). Die Engine wurde mit 40 Paritätsszenarien gegen die Web-Engine geprüft (gleiche Schritte, Variablen und Ereignisse); die Bildschirme wurden im Emulator auf Persisch (RTL) und Englisch verifiziert. Bearbeitet wird der Flow nur im Dashboard.

Ankündigungen und Warnungen des Posteingangs

Seit 1.0.0-beta04 zeigt das SDK die Ankündigungen, die Sie im Panel für den Posteingang eingerichtet haben, von selbst und ohne Code oben auf dem Startbildschirm der App an. Die Einstellungen sind dieselben wie für das Web-Widget (Einstellungen des Posteingangs, Abschnitt „Widget announcements“); wie Sie sie anlegen und formulieren, lesen Sie in Ankündigungen und Warnungen im Support-Widget.

• Wo sie erscheinen: oben auf dem Startbildschirm (Home), auf dem Ticket-Bildschirm, wenn er als Startbildschirm dient, und im Pre-Chat-Formular, oberhalb des Flow-Runners und der Startkarten. Das Störungshinweis-Banner folgt danach.
• Bis zu zwei, auf zwei Stufen: eine gelbe „Ankündigung“ mit Info-Symbol und eine rote „Warnung“ mit Warnsymbol, im hellen und dunklen Design sowie rechtsläufig (RTL).
• Text und Links: fette Passagen und Links auf einem Teil des Textes. Nur http, https, mailto und tel werden geöffnet, in der passenden App (Browser, Telefon, E-Mail) und nie in einer WebView.
• Bild: ein https-Bild mit einer Beschreibung für TalkBack und einem optionalen Link; schlägt das Laden fehl, wird es ausgeblendet.
• Schließen: Eine schließbare Ankündigung hat eine Schaltfläche zum Schließen, und die Entscheidung des Nutzers wird auf diesem Gerät gespeichert. Ändern Sie im Panel den Text, die Stufe oder die Option „Visitors can close it“, wird die Ankündigung erneut angezeigt.
• Zeitplan: Der Server sendet nur eingeschaltete Ankündigungen innerhalb ihres Zeitfensters; das SDK muss dafür nichts tun.
• Ältere Server: Hat der Server diese Funktion nicht, wird keine Ankündigung angezeigt, und der Rest des SDK funktioniert wie gewohnt.

Haben Sie eine eigene Oberfläche gebaut, liegen die noch nicht geschlossenen Ankündigungen in einem StateFlow. HodhodChat und Hodhod.open erledigen das selbst und brauchen den folgenden Code nicht:

val items by Hodhod.repository.announcements.collectAsState()   // not closed yet, refreshed with the widget config

// e.g. from a close button of your own UI; ignored for announcements visitors cannot close
items.firstOrNull()?.let { Hodhod.repository.dismissAnnouncement(it.id) }

R8 und ProGuard

Die erforderlichen Regeln sind in den Bibliotheken enthalten (consumer-rules.pro), Sie müssen für einen Release-Build also nichts ergänzen. Sie bewahren die Serializer der SDK-Modelle und HodhodChatActivity, die Hodhod.open über den Namen sucht. Haben Sie bereits eine Regel für die Activity, schadet eine Wiederholung nicht. Wenn Sie shrinkResources aktivieren, bleiben die Texte und Schriften des SDK durch die mitgelieferte Keep-Datei erhalten.

Fehlerbehebung

Der Chat-Bildschirm zeigt einen Fehler oder lädt nicht. Lesen Sie Hodhod.state; im Zustand Failed enthält es einen code:

• not_found: websiteToken oder baseUrl ist falsch.
• network: Das Telefon erreicht den Server nicht.
• suspended: Das Hodhod-Konto ist gesperrt.
• server: ein Serverfehler; versuchen Sie es gleich noch einmal.
• cleartext: Sie haben eine http://-Adresse übergeben.

Ein lokaler Server (10.0.2.2) verbindet sich nicht. Im Emulator ist das localhost Ihres Rechners 10.0.2.2. Da die Adresse http:// verwendet, brauchen Sie zwei Dinge, beide nur für Debug-Builds: Übergeben Sie allowCleartext = true in HodhodConfig, und erlauben Sie in einer Debug-network_security_config Klartextverkehr nur für 10.0.2.2 (die Beispiel-App des SDK enthält ein Beispiel). Verwenden Sie beides nicht in Release-Builds.

Nachrichten kommen nicht live an, und das Banner „Keine Verbindung“ erscheint. Live-Updates laufen über einen WebSocket auf dem Pfad /cable. Ein Firmen-Proxy, eine Firewall oder ein CDN kann das WebSocket-Upgrade blockieren. Das SDK verbindet sich mit zunehmender Verzögerung neu; probieren Sie denselben Pfad in einem anderen Netzwerk.

Die Sprache ist falsch. Übergeben Sie locale ausdrücklich in HodhodConfig. Ohne diese Angabe wird die Sprache des Hodhod-Kontos (auf dem Server) verwendet, danach die Gerätesprache. Codes wie fa-IR werden akzeptiert und auf fa verkürzt.

identify schlägt fehl. Meist ist der identifierHash falsch. Prüfen Sie, ob Sie den HMAC-Schlüssel des Posteingangs verwendet haben (nicht das websiteToken), ob der identifier in der App und im Backend identisch ist und ob der Hash als Hex geschrieben ist.

Häufig gestellte Fragen