Integrar o SDK React Native DobroDesk

Instalar pacotes e executar sincronização nativa

As páginas dos pacotes são https://www.npmjs.com/package/@dobrodesk/react-native-sdk/v/0.2.0 e https://www.npmjs.com/package/@dobrodesk/mobile-protocol/v/0.2.0. Mantenha as versões publicadas alinhadas. O autolinking do React Native lê codegenConfig do wrapper durante o build nativo. Não copie manualmente módulos nativos privados para a app.

Depois de instalar, execute a instalação CocoaPods para iOS e registe o repositório Android antes do primeiro build Android. Mantenha a New Architecture ativa para que NativeDobroDeskMobileSdkSpec fique disponível na bridge.

O pacote React Native iOS publicado na versão 0.2.0 passa as verificações de uma app consumidora limpa para registar dependências do Podspec, descobrir rnconfig e gerar cabeçalhos Codegen. Instale os pacotes correspondentes, execute o CocoaPods e use o fluxo normal de autolinking do React Native.

npm install @dobrodesk/react-native-sdk@0.2.0 @dobrodesk/mobile-protocol@0.2.0

Registar o Podspec iOS

O pacote publicado 0.2.0 contém os artefactos nativos para uma integração React Native iOS limpa. Depois de instalar os pacotes correspondentes e o CocoaPods, deixe o autolinking do React Native fornecer a bridge e os cabeçalhos Codegen gerados.

# React Native iOS 0.2.0 passes the clean consumer integration checks.
# Install the matching packages and run CocoaPods.
# React Native autolinking provides the corrected root Podspec and bridge setup.

target "YourApp" do
  # Keep the generated React Native target configuration here.
end

Registar o repositório Maven Android incluído

O pacote React Native publicado inclui native/maven com as coordenadas do motor base, do controlador UI e da UI. Registe-o em android/settings.gradle ou settings.gradle.kts em dependencyResolutionManagement. O build Android do wrapper resolverá então com.dobrodesk:dobrodesk-sdk:0.2.0 e com.dobrodesk:dobrodesk-ui:0.2.0 a partir desse repositório local.

// Groovy template: android/settings.gradle
import org.gradle.api.initialization.resolve.RepositoriesMode

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven { url = uri("$rootDir/../node_modules/@dobrodesk/react-native-sdk/native/maven") }
  }
}

// Kotlin DSL template: android/settings.gradle.kts
import org.gradle.api.initialization.resolve.RepositoriesMode

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven { url = uri("$rootDir/../node_modules/@dobrodesk/react-native-sdk/native/maven") }
  }
}

Alinhar a toolchain Android do host

Os artefactos Android 0.2.0 usam Kotlin Gradle Plugin 2.2.0 e Java 17. O modelo atual do React Native 0.87 já usa este nível de Kotlin. Um modelo React Native 0.76.x pode incluir um plugin Kotlin mais antigo. Atualize o plugin do host antes da compilação e mantenha Java 17 explícito.

O React Native 0.76.x também aplica um hook de alinhamento da versão Java que entra em conflito com Kotlin 2.2.0. Desative esse hook apenas para o perfil de host antigo e mantenha a New Architecture ativada.

Use para o perfil mínimo testado do React Native 0.76 Android Gradle Plugin 8.6.0, Gradle 8.14.3, Kotlin Gradle Plugin 2.2.0, Java 17, compileSdk 36 e minSdk 26.

O host de compatibilidade atual do React Native 0.87 usa as versões geradas por essa release, incluindo Android Gradle Plugin 9.2.1, Gradle 9.4.1, Kotlin Gradle Plugin 2.2.0 e Java 21. Mantenha as versões geradas para o perfil atual.

// android/build.gradle in an older React Native host
buildscript {
  ext {
    minSdkVersion = 26
    compileSdkVersion = 36
    kotlinVersion = "2.2.0"
  }
}

// android/app/build.gradle for the React Native 0.76.x profile
android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
  }
}

kotlin {
  jvmToolchain(17)
}

// android/gradle/wrapper/gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip

// android/gradle.properties for the React Native 0.76.x profile
react.internal.disableJavaVersionAlignment=true

Configurar e apresentar o cliente wrapper

O wrapper suporta React Native 0.76 a 0.87 com a New Architecture ativada. Depois de instalar os pacotes e configurar os projetos nativos, forneça credentialProvider a partir da sua aplicação host.

credentialProvider é fornecido pela aplicação host e devolve um objeto com um JWT de identidade do cliente de curta duração. Não use um support API token no bundle da app.

import { createDobroDeskReactNativeClient } from "@dobrodesk/react-native-sdk";
import type { DobroDeskSdkConfig } from "@dobrodesk/mobile-protocol";

const config: DobroDeskSdkConfig = {
  apiOrigin: "https://dobrodesk.com",
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  accountScope: currentCustomer.id,
  locale: "en",
  credentialProvider: async () => ({
    authorizationToken: await loadDobroDeskToken(),
  }),
};

const client = createDobroDeskReactNativeClient(config);
await client.presentWidget();

Controlar o acionador e a visibilidade do widget integrado

Use visible={visible} quando uma rota mantida ou um overlay ocultar temporariamente o widget integrado. A superfície nativa pausa o trabalho visível e mantém o cliente, a sessão e o rascunho. Use loadingBuilder para um estado de preparação personalizado e errorBuilder ou onError para o aviso de erro recuperável do host.

Volte a usar visible=true quando a rota regressar. Reutilize o mesmo cliente e não monte várias superfícies integradas para uma sessão.

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 {
  DobroDeskWidgetView,
  type DobroDeskWidgetViewProps,
} from "@dobrodesk/react-native-sdk";

type SupportPanelProps = {
  client: DobroDeskWidgetViewProps["client"];
  visible?: boolean;
  onError?: DobroDeskWidgetViewProps["onError"];
};

export function SupportPanel({
  client,
  visible = true,
  onError,
}: SupportPanelProps) {
  return (
    <DobroDeskWidgetView
      client={client}
      options={{ locale: "en", view: "home" }}
      visible={visible}
      style={{ height: 560, width: "100%" }}
      onError={onError}
    />
  );
}

Ligar a navegação e o ciclo da conta

Chame closeWidget quando o ecrã do host for desmontado. Use resetSession para descartar uma conversa intencionalmente e logout antes de alterar accountScope. O motor nativo gere estado durável, polling e repetições. O JavaScript deve reagir a eventos tipados e não criar uma segunda fila.

O wrapper apresenta o mesmo contrato de UI nativa dos outros SDK móveis. Omita reduceMotion para que a preferência de acessibilidade do sistema host controle o movimento.

Tratar carregamento, visibilidade e acessibilidade

Use hooks de carregamento ou eventos tipados para o estado da tela hospedeira. A superfície mostra o carregamento das mensagens, a espera e as tentativas novamente para evitar um segundo indicador sobre o campo de entrada.

Oculte ou mostre a superfície durante uma navegação temporária mantendo o cliente. O widget respeita as preferências do sistema para reduzir movimento. Remover ou fechar a vista não descarta a sessão nem o rascunho.

1. Ao montar novamente, reutilize o mesmo cliente e dimensões estáveis do contêiner.
2. Use a função de visibilidade para ocultar temporariamente, sem redefinir a sessão.
3. Finalize a sessão apenas ao sair ou trocar de conta de forma intencional.

Verificar o fluxo React Native

1. Abra o widget a partir de um ecrã React Native em primeiro plano e confirme que o painel nativo é apresentado uma vez.
2. Subscreva os eventos e mostre um estado de carregamento no host apenas enquanto o SDK comunicar uma fase de carregamento ativa.
3. Envie com uma idempotency key estável, perca a conectividade e chame flushOutbox depois de a mesma conta receber um token novo. Não crie uma chave nova para um envio incerto.