Integrar o SDK Flutter DobroDesk

Instalar o pacote Flutter publicado

Fixe a versão do pacote publicado em pubspec.yaml ou adicione-a com a CLI do Flutter antes de configurar os projetos nativos do host.

flutter pub add dobrodesk_sdk:0.2.0

Configurar o host Android

O pacote Flutter publicado liga o motor e a UI Android a partir do repositório Maven local incluído. Adicione este repositório ao projeto Android raiz antes da primeira sincronização do Gradle. Defina compileSdk como 36, minSdk como 26 e as toolchains Java/Kotlin como 17. Estas definições são necessárias para os artefactos nativos 0.2.0.

Os modelos Flutter mais antigos podem usar versões do Android Gradle Plugin ou Kotlin abaixo deste mínimo. Antes de compilar, atualize em conjunto o Android Gradle Plugin e o plugin Kotlin para versões suportadas pela sua versão Flutter instalada. Não altere silenciosamente o projeto gerado durante a integração.

A combinação de host testada para Flutter 3.22.3 é Android Gradle Plugin 8.13.2, Kotlin Gradle Plugin 2.2.0, Gradle 8.14.3 e JDK 17. Os hosts gerados pelo Flutter 3.44.2 usam uma combinação compatível mais recente. Mantenha as versões geradas por essa versão do Flutter e não faça downgrade.

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

Usar FlutterFragmentActivity no Android

Mantenha a declaração package gerada pelo Flutter e altere a Activity de entrada do Android para FlutterFragmentActivity. A bridge do widget precisa do ActivityResultRegistryOwner da activity baseada em fragments. Manter FlutterActivity pode causar No ActivityResultRegistryOwner quando o widget é aberto.

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

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity : FlutterFragmentActivity()

Configurar o host iOS

Defina o target da aplicação Flutter e cada target CocoaPods para iOS 15.1 ou posterior antes de executar pod install. Mantenha o Podfile gerado pelo Flutter e adicione a definição de deployment em post_install para que o SDK e o host usem o mesmo mínimo.

O binário iOS publicado usa Swift concurrency. Use o Xcode 16.4 ou posterior, mantenha a versão do Swift compatível com a versão Flutter instalada e defina também 15.1 no Deployment Target do target Runner no 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.

Configurar e apresentar o widget

O pacote suporta Flutter 3.22.3 ou posterior, Dart 3.4 até 3.x, Android API 26 e iOS 15.1. O callback credentialProvider pertence à aplicação. Deve devolver um JWT de identidade do cliente de curta duração do seu backend. Não inclua signing secret ou support API token no 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();

Controlar o widget integrado e a visibilidade

Use visible: false quando uma rota mantida ou um overlay ocultar temporariamente a superfície Flutter. A superfície nativa mantém o cliente, a sessão e o rascunho. Se não precisar de onError, o SDK mostra o seu estado de recuperação localizado.

Volte a usar visible: true quando a rota regressar. Reutilize o mesmo cliente ao montar novamente.

DobroDeskWidgetView faz parte do pacote publicado do Mobile SDK 0.2.0. Use-o para apresentação inline e altere a visibilidade no mesmo cliente para preservar a sessão, o rascunho e a outbox offline.

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

Usar o ciclo de vida nativo partilhado

O widget é nativo nas duas plataformas e não usa o renderer web numa WebView. Use client.resetSession() quando o cliente descartar uma conversa e client.logout() antes de alterar accountScope. logout também elimina qualquer capacidade voice opcional associada.

Omita reduceMotion de presentWidget salvo quando a app tiver uma definição explícita do cliente que esteja a passar. O SDK nativo respeita por defeito a preferência do sistema para reduzir movimento.

Tratar carregamento, visibilidade e acessibilidade

A vista nativa apresenta os seus estados localizados integrados de carregamento, espera e repetição. Use os eventos tipados do cliente para um estado de carregamento do host Flutter e errorBuilder ou onError para um aviso de recuperação do host. Não sobreponha um segundo spinner ao campo de entrada enquanto o widget apresenta o estado de envio.

Mantenha a vista montada quando possível. Se a navegação a ocultar, preserve o cliente e monte novamente a vista com o mesmo cliente quando a rota regressar. A superfície nativa respeita as definições do sistema para reduzir movimento e a escala de animação. O host Flutter continua responsável pelos labels de acessibilidade, pela ordem de foco e pelos insets do teclado.

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.

Verificar o fluxo Flutter

1. Apresente a partir de uma rota Flutter visível e confirme que toques repetidos não acumulam apresentações nativas.
2. Num ecrã de desenvolvimento, execute startSession, resumeSession, sendMessage com uma idempotencyKey estável, refresh e flushOutbox.
3. Altere a definição do sistema para reduzir movimento e repita a abertura e o fecho. Confirme que o widget não introduz movimento quando o sistema o pede.