Das DobroDesk Android-SDK integrieren

Android-Release-Bundle installieren

Laden Sie https://github.com/comstud-io/dobrodesk-mobile-sdk/releases/download/v0.2.0/dobrodesk-mobile-sdk-0.2.0-bundle.tar.gz herunter und entpacken Sie es in ein stabiles Verzeichnis, das weder in den App-Quellcode noch in einen öffentlichen Upload gelangt. Das Archiv enthält das lokale Maven-Repository unter native/maven. Registrieren Sie dieses Verzeichnis in der Host-Settings-Datei, damit Gradle-Projekte mit FAIL_ON_PROJECT_REPOS gültig bleiben. Dieses Mobile-SDK-0.2.0-Release ergänzt native Inline-Flächen und Wrapper-Korrekturen. Die Android-Korrektur für geschützten Speicher ist ebenfalls enthalten. Die öffentliche API und der Vertrag der nativen Oberfläche bleiben kompatibel.

Android API 26 und neuer wird unterstützt. Die Basisartefakte werden nicht aus Maven Central geladen. Voice und Push haben eigene Koordinaten und sollten nur hinzugefügt werden, wenn der Host die entsprechenden Berechtigungen und Anbieter selbst vorbereitet.

Verwenden Sie für das native Android-Beispiel die getestete direkte Android-Hostkombination mit Android Gradle Plugin 8.13.2, Kotlin Gradle Plugin 2.2.0, Gradle 8.14.3 und Java 17 mit compileSdk 36 und minSdk 26. Behalten Sie bei einem anderen aktuellen Android-Projekt die von dessen Android- oder Framework-Release erzeugten Versionen bei, wenn sie mit dem SDK kompatibel sind.

import org.gradle.api.initialization.resolve.RepositoriesMode

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven { url = uri("<extracted-bundle>/native/maven") }
  }
}

// android/app/build.gradle.kts
android {
  compileSdk = 36
  defaultConfig { minSdk = 26 }
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
  }
}

Die drei Android-Basisartefakte deklarieren

Das entpackte lokale Repository enthält die Koordinaten für Engine, UI-Controller und UI-AAR. Deklarieren Sie alle drei im App-Modul. Der Wrapper fügt kein Repository auf Projektebene hinzu und bindet optionale Voice- oder Push-Module nicht stillschweigend ein.

dependencies {
  implementation("com.dobrodesk:dobrodesk-sdk:0.2.0")
  implementation("com.dobrodesk:dobrodesk-ui-controller:0.2.0")
  implementation("com.dobrodesk:dobrodesk-ui:0.2.0")
}

Aus einer sichtbaren Activity präsentieren

Die folgenden hosteigenen Funktionen rufen Ihren Backend-Token-Endpunkt auf und geben die stabile ID des aktuellen Kunden sowie sein kurzlebiges Identitäts-JWT zurück. Das SDK präsentiert nur, solange die Activity sichtbar ist.

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.lifecycle.lifecycleScope
import com.dobrodesk.sdk.DobroDeskConfiguration
import com.dobrodesk.sdk.ui.DobroDeskAndroidClientFactory
import com.dobrodesk.sdk.ui.DobroDeskWidgetBridgePresenter
import java.time.Duration
import kotlinx.coroutines.launch

class MainActivity : ComponentActivity() {
  private var presenter: DobroDeskWidgetBridgePresenter? = null
  private val client by lazy {
    DobroDeskAndroidClientFactory.create(
      context = this,
      configuration = DobroDeskConfiguration(
        apiOrigin = "https://dobrodesk.com",
        integrationId = "wgt_0123456789abcdef0123456789abcdef",
        accountScope = currentCustomerId(),
        credentialProvider = { loadDobroDeskToken() },
        pollInterval = Duration.ofSeconds(1),
      ),
    )
  }

  override fun onCreate(state: Bundle?) {
    super.onCreate(state)
    lifecycleScope.launch {
      presenter = DobroDeskWidgetBridgePresenter.present(
        activity = this@MainActivity,
        client = client,
        options = mapOf("locale" to "en"),
        onClosed = { presenter = null },
      )
    }
  }

  override fun onDestroy() {
    presenter?.detach()
    presenter = null
    super.onDestroy()
  }
}

Eigenen Trigger oder Inline-Fläche verwenden

Übergeben Sie dem suspend helper eine sichtbare Activity und ein bereits an window angehängtes FrameLayout. Der Helper erstellt die erforderlichen JsonObject-Optionen, fügt handle.view über Dispatchers.Main.immediate ein und schließt den Handle, wenn der Host vor oder nach dem Mounten entfernt wird.

Der eigene Button bleibt per Tastatur erreichbar und erhält aria-controls sowie aria-expanded. Verwenden Sie beim erneuten Mounten denselben Client, dieselbe Sitzung und denselben Entwurf.

Die Inline-APIs gehören zu den veröffentlichten Mobile-SDK-0.2.0-Artefakten. Verwenden Sie die Inline-Fläche, wenn der Host die Platzierung steuert, und die modale Darstellung für einen vom Host verwalteten Vollbildablauf.

import android.app.Activity
import android.view.View
import android.view.ViewGroup
import android.widget.FrameLayout
import com.dobrodesk.sdk.DobroDeskClient
import com.dobrodesk.sdk.ui.DobroDeskWidgetBridgePresenter
import com.dobrodesk.sdk.ui.DobroDeskWidgetEmbeddedHandle
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

suspend fun mountSupportPanel(
  activity: Activity,
  client: DobroDeskClient,
  supportContainer: FrameLayout,
): DobroDeskWidgetEmbeddedHandle? {
  check(supportContainer.isAttachedToWindow) {
    "Attach the support container before mounting the widget"
  }
  var embeddedHandle: DobroDeskWidgetEmbeddedHandle? = null
  val detachListener = object : View.OnAttachStateChangeListener {
    override fun onViewAttachedToWindow(view: View) = Unit
    override fun onViewDetachedFromWindow(view: View) {
      embeddedHandle?.close()
    }
  }
  val handle = DobroDeskWidgetBridgePresenter.createEmbedded(
    activity = activity,
    client = client,
    options = buildJsonObject {
      put("locale", "en")
      put("view", "home")
    },
    onClosed = {
      supportContainer.removeOnAttachStateChangeListener(detachListener)
      embeddedHandle = null
    },
  )
  embeddedHandle = handle
  var attached = false
  withContext(Dispatchers.Main.immediate) {
    if (supportContainer.isAttachedToWindow && !activity.isFinishing && !activity.isDestroyed) {
      supportContainer.addView(
        handle.view,
        ViewGroup.LayoutParams(
          ViewGroup.LayoutParams.MATCH_PARENT,
          ViewGroup.LayoutParams.MATCH_PARENT,
        ),
      )
      supportContainer.addOnAttachStateChangeListener(detachListener)
      handle.setVisible(true)
      attached = true
    }
  }
  if (!attached) {
    handle.close()
    return null
  }
  return handle
}

Android-Lebenszyklus und Identität behandeln

credentialProvider ist eine vom Host bereitgestellte suspend-Funktion, die ein kurzlebiges Kundenidentitäts-JWT zurückgibt. Der native Code schützt die dauerhafte Outbox mit Android Keystore und bindet sie an accountScope. Speichern Sie kein Support-API-Token in den App-Einstellungen.

Rufen Sie presenter.close() auf, wenn der Host-Bildschirm verworfen wird, und client.resetSession(), wenn eine Unterhaltung verworfen wird. Der direkte Android-Client hat kein logout: Setzen Sie ihn zurück, verwerfen Sie ihn und erstellen Sie vor der Änderung von accountScope einen neuen Client. Ohne ausdrücklichen Override folgt das Widget der Systemeinstellung für reduzierte Bewegung.

Laden, Sichtbarkeit und Barrierefreiheit behandeln

Nutzen Sie Loading-Hooks oder typisierte Events für den Ladezustand des Hosts. Die Oberfläche zeigt Nachrichtenladen, Warten und Wiederholungen selbst an, damit kein zweiter Spinner das Eingabefeld überlagert.

Verbergen oder zeigen Sie die Oberfläche bei einer vorübergehenden Navigation und behalten Sie den Client. Das Widget respektiert die Systemoptionen für reduzierte Bewegung. Ein Entfernen oder Schließen verwirft weder Sitzung noch Entwurf.

1. Verwenden Sie beim erneuten Mounten denselben Client und feste Host-Abmessungen.
2. Verwenden Sie die Sichtbarkeitsfunktion für vorübergehendes Ausblenden und keine Session-Reset-Funktion.
3. Beenden Sie die Sitzung erst bei Logout oder einem bewussten Kontowechsel.

Android-Ablauf prüfen

1. Präsentieren Sie aus einer sichtbaren Activity und prüfen Sie, dass wiederholtes Tippen keine überlappenden Presenter erzeugt.
2. Senden Sie eine Nachricht mit stabilem idempotency key, schicken Sie die App in den Hintergrund und öffnen Sie sie erneut. Prüfen Sie, dass die ausstehende Nachricht nach der Rückkehr des Netzwerks mit demselben Schlüssel wiederholt wird.
3. Verwenden Sie resetSession für ein bewusstes Verwerfen. Setzen Sie den direkten Client vor dem Kontowechsel zurück und verwerfen Sie ihn, erstellen Sie einen neuen Client und prüfen Sie, dass das nächste Konto mit einer leeren Unterhaltung beginnt.