Intégrer le SDK React Native DobroDesk

Installer les packages et synchroniser le natif

Les pages des packages sont https://www.npmjs.com/package/@dobrodesk/react-native-sdk/v/0.2.0 et https://www.npmjs.com/package/@dobrodesk/mobile-protocol/v/0.2.0. Gardez les versions publiées alignées. L'autolinking React Native lit la codegenConfig du wrapper pendant le build natif. Ne copiez pas manuellement les modules natifs privés dans l'application.

Après l'installation, installez les CocoaPods pour iOS et enregistrez le dépôt Android avant le premier build Android. Gardez la New Architecture activée afin que le NativeDobroDeskMobileSdkSpec généré soit disponible pour le bridge.

Le package React Native iOS publié en 0.2.0 réussit les vérifications d'un projet consommateur propre pour les dépendances Podspec, la découverte de rnconfig et les en-têtes Codegen générés. Installez les packages correspondants, exécutez CocoaPods et utilisez le flux d'autolinking React Native normal.

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

Enregistrer le Podspec iOS

Le package publié en 0.2.0 contient les artefacts natifs nécessaires à une intégration React Native iOS propre. Après l'installation des packages correspondants et de CocoaPods, laissez l'autolinking React Native fournir le bridge et les en-têtes Codegen générés.

# 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

Enregistrer le dépôt Maven Android inclus

Le package React Native publié contient native/maven avec les coordonnées du moteur de base, du contrôleur d'interface et de l'interface. Enregistrez-le dans dependencyResolutionManagement depuis android/settings.gradle ou settings.gradle.kts. Le build Android du wrapper résout alors com.dobrodesk:dobrodesk-sdk:0.2.0 et com.dobrodesk:dobrodesk-ui:0.2.0 depuis ce dépôt 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") }
  }
}

Aligner la toolchain Android de l'hôte

Les artefacts Android 0.2.0 utilisent Kotlin Gradle Plugin 2.2.0 et Java 17. Le modèle React Native 0.87 actuel utilise déjà ce niveau de Kotlin. Un modèle React Native 0.76.x peut inclure un plugin Kotlin plus ancien. Mettez à jour le plugin de l'hôte avant la compilation et gardez Java 17 explicitement configuré.

React Native 0.76.x applique aussi un hook d'alignement de version Java qui entre en conflit avec Kotlin 2.2.0. Désactivez ce hook uniquement pour l'ancien profil d'hôte et gardez la New Architecture activée.

Utilisez pour le profil minimal React Native 0.76 testé Android Gradle Plugin 8.6.0, Gradle 8.14.3, Kotlin Gradle Plugin 2.2.0, Java 17, compileSdk 36 et minSdk 26.

L'hôte de compatibilité React Native 0.87 actuel utilise les versions générées par cette release, notamment Android Gradle Plugin 9.2.1, Gradle 9.4.1, Kotlin Gradle Plugin 2.2.0 et Java 21. Conservez les versions générées pour le profil actuel.

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

Configurer et présenter le client wrapper

Le wrapper prend en charge React Native 0.76 à 0.87 avec la New Architecture activée. Après l'installation des packages et la configuration des projets natifs, fournissez credentialProvider depuis votre application hôte.

credentialProvider est fourni par votre application hôte et renvoie un objet contenant un JWT d'identité client de courte durée. N'utilisez pas de support API token dans le bundle de l'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();

Gérer le déclencheur et la visibilité du widget intégré

Utilisez visible={visible} lorsqu'une route conservée ou un overlay masque temporairement le widget intégré. La surface native met en pause le travail visible et conserve le client, la session et le brouillon. Utilisez loadingBuilder pour un état de préparation personnalisé et errorBuilder ou onError pour l'avis d'erreur récupérable de l'hôte.

Rétablissez visible=true lorsque la route revient. Réutilisez le même client et ne montez pas plusieurs surfaces intégrées pour une session.

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 {
  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}
    />
  );
}

Relier la navigation et le cycle du compte

Appelez closeWidget lorsque l'écran hôte est démonté. Utilisez resetSession pour abandonner volontairement une conversation et logout avant de changer accountScope. Le moteur natif gère l'état durable, le polling et les nouvelles tentatives. JavaScript doit réagir aux événements typés sans lancer une seconde file.

Le wrapper présente le même contrat d'interface native que les autres SDK mobiles. Omettez reduceMotion afin que la préférence d'accessibilité du système hôte contrôle les mouvements.

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

Utilisez les hooks de chargement ou les événements typés pour l'état de l'écran hôte. La surface affiche elle-même le chargement des messages, l'attente et les nouvelles tentatives afin d'éviter un second indicateur sur le champ de saisie.

Masquez ou affichez la surface lors d'une navigation temporaire en conservant le client. Le widget respecte les préférences système de réduction des mouvements. Le retrait ou la fermeture ne supprime ni la session ni le brouillon.

1. Lors du nouveau montage, réutilisez le même client et des dimensions stables pour le conteneur.
2. Utilisez la fonction de visibilité pour un masquage temporaire, sans réinitialiser la session.
3. Terminez la session uniquement lors de la déconnexion ou d'un changement de compte volontaire.

Vérifier le flux React Native

1. Ouvrez le widget depuis un écran React Native au premier plan et confirmez que le panneau natif est présenté une seule fois.
2. Abonnez-vous aux événements et n'affichez un état de chargement côté hôte que lorsque le SDK signale une phase de chargement active.
3. Envoyez avec un idempotency key stable, perdez la connectivité et appelez flushOutbox après que le même compte a reçu un nouveau token. Ne générez pas de nouvelle clé pour un envoi incertain.