Intégrer le SDK Flutter DobroDesk

Installer le package Flutter publié

Épinglez la version publiée du package dans pubspec.yaml ou ajoutez-la avec la CLI Flutter avant de configurer les projets natifs de l'hôte.

flutter pub add dobrodesk_sdk:0.2.0

Configurer l'hôte Android

Le package Flutter publié relie le moteur et l'interface Android depuis son dépôt Maven local inclus. Ajoutez ce dépôt au projet Android racine avant la première synchronisation Gradle. Définissez compileSdk à 36, minSdk à 26 et les toolchains Java/Kotlin à 17. Ces réglages sont requis par les artefacts natifs 0.2.0.

Les anciens modèles Flutter peuvent utiliser des versions d'Android Gradle Plugin ou de Kotlin inférieures à ce niveau. Avant la compilation, mettez à niveau ensemble l'Android Gradle Plugin et le plugin Kotlin vers des versions prises en charge par votre version Flutter installée. Ne modifiez pas silencieusement le projet généré pendant l'intégration.

La combinaison d'hôte testée pour Flutter 3.22.3 est Android Gradle Plugin 8.13.2, Kotlin Gradle Plugin 2.2.0, Gradle 8.14.3 et JDK 17. Les hôtes générés par Flutter 3.44.2 utilisent une combinaison compatible plus récente. Conservez les versions générées par cette version de Flutter et ne les rétrogradez pas.

// 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.

Utiliser FlutterFragmentActivity sur Android

Conservez la déclaration package générée par Flutter et remplacez l'Activity d'entrée Android par FlutterFragmentActivity. Le bridge du widget a besoin de l'ActivityResultRegistryOwner de l'activity basée sur les fragments. Conserver FlutterActivity peut provoquer No ActivityResultRegistryOwner à l'ouverture du widget.

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

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity : FlutterFragmentActivity()

Configurer l'hôte iOS

Définissez la cible de l'application Flutter et chaque cible CocoaPods sur iOS 15.1 ou une version ultérieure avant pod install. Conservez le Podfile généré par Flutter et ajoutez le réglage de déploiement dans post_install afin que le SDK et l'hôte utilisent la même version minimale.

Le binaire iOS publié utilise Swift Concurrency. Utilisez Xcode 16.4 ou une version ultérieure, conservez la version de Swift prise en charge par votre version Flutter installée et définissez également 15.1 comme Deployment Target de la cible Runner dans Xcode.

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.

Configurer et présenter le widget

Le package prend en charge Flutter 3.22.3 ou ultérieur, Dart 3.4 à 3.x, Android API 26 et iOS 15.1. Le callback credentialProvider est une fonction de l'application. Il doit renvoyer un JWT d'identité client de courte durée depuis votre backend. N'intégrez ni signing secret ni support API token dans le bundle Flutter.

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

Gérer le widget intégré et sa visibilité

Utilisez visible: false lorsqu'une route conservée ou un overlay masque temporairement la surface Flutter. La surface native conserve le client, la session et le brouillon. Si aucun callback onError n'est nécessaire, le SDK affiche son état de récupération localisé.

Rétablissez visible: true lorsque la route revient. Réutilisez le même client lors du nouveau montage.

DobroDeskWidgetView fait partie du package Mobile SDK 0.2.0 publié. Utilisez-le pour la présentation inline et modifiez la visibilité sur le même client afin de préserver la session, le brouillon et l'outbox hors ligne.

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

Utiliser le cycle de vie natif partagé

Le widget est natif sur les deux plateformes et n'utilise pas le renderer web dans une WebView. Utilisez client.resetSession() lorsque le client abandonne une conversation et client.logout() avant de changer accountScope. logout libère aussi une éventuelle capacité vocale optionnelle attachée.

Omettez reduceMotion de presentWidget sauf si votre app possède un réglage explicite du client que vous transmettez. Le SDK natif respecte par défaut la préférence système de réduction des mouvements.

Gérer le chargement, la visibilité et l'accessibilité

La vue native affiche ses états intégrés et localisés de chargement, d'attente et de nouvelle tentative. Utilisez les événements typés du client pour un état de chargement Flutter autour de la vue et errorBuilder ou onError pour un avis de récupération de l'hôte. N'ajoutez pas un second spinner au-dessus du champ de saisie pendant que le widget affiche son état d'envoi.

Gardez la vue montée lorsque c'est possible. Si la navigation la masque, conservez le client et remontez la vue avec le même client au retour de la route. La surface native respecte les réglages système de réduction des mouvements et d'échelle d'animation. L'hôte Flutter reste responsable des labels d'accessibilité, de l'ordre du focus et des insets du clavier.

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.

Vérifier le flux Flutter

1. Présentez depuis une route Flutter visible et confirmez que des appuis répétés n'empilent pas les présentations natives.
2. Depuis un écran de développement, testez startSession, resumeSession, sendMessage avec un idempotencyKey stable, refresh et flushOutbox.
3. Modifiez le réglage système de réduction des mouvements et répétez l'ouverture et la fermeture. Confirmez que le widget n'ajoute aucun mouvement lorsque le système le demande.