Das DobroDesk Flutter-SDK integrieren

Veröffentlichtes Flutter-Paket installieren

Fixieren Sie die veröffentlichte Paketversion in pubspec.yaml oder fügen Sie sie mit der Flutter-CLI hinzu, bevor Sie die nativen Hostprojekte konfigurieren.

flutter pub add dobrodesk_sdk:0.2.0

Android-Host konfigurieren

Das veröffentlichte Flutter-Paket bindet die Android-Engine und die UI über sein enthaltenes lokales Maven-Repository ein. Fügen Sie dieses Repository vor der ersten Gradle-Synchronisierung zum Android-Stammprojekt hinzu. Setzen Sie compileSdk auf 36, minSdk auf 26 und die Java/Kotlin-Toolchains auf 17. Diese Einstellungen werden von den nativen Artefakten 0.2.0 benötigt.

Ältere Flutter-Vorlagen können Android-Gradle-Plugin- oder Kotlin-Versionen unterhalb dieser Grenze enthalten. Aktualisieren Sie das Android-Gradle-Plugin und das Kotlin-Plugin vor dem Build gemeinsam auf Versionen, die Ihre installierte Flutter-Version unterstützt. Ändern Sie das generierte Projekt während der Integration nicht stillschweigend.

Die getestete Host-Kombination für Flutter 3.22.3 ist Android Gradle Plugin 8.13.2, Kotlin Gradle Plugin 2.2.0, Gradle 8.14.3 und JDK 17. Von Flutter 3.44.2 erzeugte Hosts verwenden eine neuere kompatible Kombination. Behalten Sie die von dieser Flutter-Version erzeugten Versionen bei und führen Sie kein Downgrade durch.

// Kotlin DSL root template: android/build.gradle.kts
allprojects {
  repositories {
    google()
    mavenCentral()
    maven { url = uri(project(":dobrodesk_sdk").projectDir.resolve("../native/maven")) }
  }
}

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

// Groovy root template: android/build.gradle
allprojects {
  repositories {
    google()
    mavenCentral()
    maven { url = uri(new File(project(":dobrodesk_sdk").projectDir, "../native/maven")) }
  }
}

// Keep the equivalent compileSdk/minSdk, Java 17 and Kotlin 17 settings in
// android/app/build.gradle when the generated app uses Groovy DSL.

FlutterFragmentActivity unter Android verwenden

Behalten Sie die von Flutter erzeugte package-Deklaration bei und ändern Sie die Android-Einstiegs-Activity zu FlutterFragmentActivity. Die Widget-Bridge benötigt den ActivityResultRegistryOwner der Fragment-Activity. Mit der erzeugten FlutterActivity kann das Öffnen des Widgets mit No ActivityResultRegistryOwner abstürzen.

package com.example.app // keep the package generated for your app

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity : FlutterFragmentActivity()

iOS-Host konfigurieren

Setzen Sie das Flutter-App-Target und jedes CocoaPods-Target vor pod install auf iOS 15.1 oder höher. Behalten Sie das generierte Flutter-Podfile bei und ergänzen Sie die Deployment-Einstellung in post_install, damit SDK und Host dieselbe Untergrenze verwenden.

Das veröffentlichte iOS-Binary verwendet Swift Concurrency. Verwenden Sie Xcode 16.4 oder neuer sowie die von Ihrer installierten Flutter-Version unterstützte Swift-Version und setzen Sie den Deployment Target des Runner-Targets in Xcode ebenfalls auf 15.1.

platform :ios, '15.1'

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.1'
    end
  end
end

# Also set Runner > Deployment Target to 15.1 in Xcode.

Widget konfigurieren und anzeigen

Das Paket unterstützt Flutter 3.22.3 oder neuer, Dart 3.4 bis 3.x, Android API 26 und iOS 15.1. Der credentialProvider-Callback gehört zur Anwendung. Er muss ein kurzlebiges Kundenidentitäts-JWT von Ihrem Backend zurückgeben. Binden Sie weder Signier-Geheimnis noch Support-API-Token in das Flutter-Bundle ein.

import "package:dobrodesk_sdk/dobrodesk_sdk.dart";

final client = DobroDeskFlutterClient(
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  apiOrigin: "https://dobrodesk.com",
  accountScope: currentCustomer.id,
  locale: "en",
  credentialProvider: () async => loadDobroDeskToken(),
);

await client.presentWidget();

Inline-Widget und Sichtbarkeit steuern

Setzen Sie visible: false, wenn eine Keep-alive-Route oder ein Overlay die Flutter-Fläche vorübergehend ausblendet. Die native Fläche behält Client, Sitzung und Entwurf. Wenn kein onError-Callback nötig ist, zeigt das SDK seine lokalisierte Wiederherstellungsanzeige.

Setzen Sie visible wieder auf true, wenn die Route zurückkehrt. Verwenden Sie denselben Client beim erneuten Mounten.

DobroDeskWidgetView gehört zum veröffentlichten Mobile-SDK-0.2.0-Paket. Verwenden Sie es für die Inline-Darstellung und ändern Sie die Sichtbarkeit am selben Client, damit Sitzung, Entwurf und Offline-Outbox erhalten bleiben.

import "package:flutter/widgets.dart";
import "package:dobrodesk_sdk/dobrodesk_sdk.dart";

Widget buildSupportPanel(
  DobroDeskFlutterClient client, {
  bool routeIsVisible = true,
}) {
  return SizedBox(
    height: 560,
    child: DobroDeskWidgetView(
      client: client,
      options: const NativeWidgetOptions(
        locale: "en",
        view: "home",
      ),
      visible: routeIsVisible,
    ),
  );
}

Gemeinsamen nativen Lebenszyklus verwenden

Das Widget ist auf beiden Plattformen nativ und verwendet den Web-Renderer nicht in einer WebView. Verwenden Sie client.resetSession(), wenn die Kundin oder der Kunde eine Unterhaltung verwirft, und client.logout() vor der Änderung von accountScope. logout gibt außerdem eine verbundene optionale Voice-Funktion frei.

Lassen Sie reduceMotion in presentWidget weg, sofern Ihre App keine ausdrückliche Kundeneinstellung weitergibt. Das native SDK beachtet standardmäßig die Systemeinstellung für reduzierte Bewegung.

Laden, Sichtbarkeit und Barrierefreiheit behandeln

Die native Ansicht zeigt ihre integrierten lokalisierten Lade-, Warte- und Wiederholungszustände. Verwenden Sie typisierte Client-Events für einen umgebenden Flutter-Ladezustand und errorBuilder oder onError für einen behebbaren Hinweis des Hosts. Legen Sie keinen zweiten Spinner über das Eingabefeld, während das Widget seinen Sendezustand anzeigt.

Behalten Sie die Ansicht nach Möglichkeit montiert. Wenn die Navigation sie ausblendet, behalten Sie den Client und mounten Sie die Ansicht nach der Rückkehr mit demselben Client erneut. Die native Oberfläche folgt den Systemoptionen für reduzierte Bewegung und Animationsskala. Der Flutter-Host bleibt für Accessibility-Labels, Fokusreihenfolge und Tastaturvermeidung verantwortlich.

1. Give the parent a stable height and rebuild with the same client after a route remount.
2. Do not call resetSession or logout when the view is temporarily hidden.
3. Call logout and dispose the client only when the account ends, then create a new client for the next account.

Flutter-Ablauf prüfen

1. Präsentieren Sie aus einer sichtbaren Flutter-Route und prüfen Sie, dass wiederholtes Tippen keine nativen Präsentationen stapelt.
2. Führen Sie aus einem Entwicklungsbildschirm startSession, resumeSession, sendMessage mit stabilem idempotencyKey, refresh und flushOutbox aus.
3. Ändern Sie die Systemoption für reduzierte Bewegung und wiederholen Sie das Öffnen und Schließen. Prüfen Sie, dass das Widget keine Bewegung einführt, wenn das System reduzierte Bewegung verlangt.