Das DobroDesk React-Native-SDK integrieren

Pakete installieren und native Synchronisierung ausführen

Die Paket-Seiten sind https://www.npmjs.com/package/@dobrodesk/react-native-sdk/v/0.2.0 und https://www.npmjs.com/package/@dobrodesk/mobile-protocol/v/0.2.0. Halten Sie die veröffentlichten Versionen synchron. Das React-Native-Autolinking liest beim nativen Build die codegenConfig des Wrappers. Kopieren Sie keine privaten nativen Quellmodule manuell in die App.

Führen Sie nach der Installation die CocoaPods-Installation für iOS aus und registrieren Sie das Android-Repository vor dem ersten Android-Build. Lassen Sie die New Architecture aktiviert, damit die generierte NativeDobroDeskMobileSdkSpec für die Bridge verfügbar ist.

Das veröffentlichte React-Native-iOS-Paket 0.2.0 besteht die Prüfungen einer sauberen Consumer-App für Podspec-Abhängigkeiten, rnconfig-Erkennung und generierte Codegen-Header. Installieren Sie die passenden Pakete, führen Sie CocoaPods aus und verwenden Sie den normalen React-Native-Autolinking-Ablauf.

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

iOS-Podspec registrieren

Das veröffentlichte Paket 0.2.0 enthält die nativen Artefakte für eine saubere React-Native-iOS-Integration. Lassen Sie React Native nach der Installation der passenden Pakete und CocoaPods die Bridge und generierten Codegen-Header über Autolinking bereitstellen.

# 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

Das gebündelte Android-Maven-Repository registrieren

Das veröffentlichte React-Native-Paket enthält native/maven mit Engine-, UI-Controller- und UI-Koordinaten. Registrieren Sie es unter dependencyResolutionManagement aus android/settings.gradle oder settings.gradle.kts. Der Android-Build des Wrappers löst anschließend com.dobrodesk:dobrodesk-sdk:0.2.0 und com.dobrodesk:dobrodesk-ui:0.2.0 aus diesem lokalen Repository auf.

// 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") }
  }
}

Android-Toolchain des Hosts ausrichten

Die Android-Artefakte 0.2.0 verwenden Kotlin Gradle Plugin 2.2.0 und Java 17. Die aktuelle React-Native-0.87-Vorlage verwendet diese Kotlin-Version bereits. Eine React-Native-0.76.x-Vorlage kann ein älteres Kotlin-Plugin enthalten. Aktualisieren Sie es vor dem Build und lassen Sie Java 17 explizit gesetzt.

React Native 0.76.x verwendet außerdem einen Java-Version-Alignment-Hook, der mit Kotlin 2.2.0 kollidiert. Deaktivieren Sie diesen Hook nur für das ältere Host-Profil und lassen Sie die New Architecture aktiviert.

Verwenden Sie für das getestete minimale React-Native-0.76-Hostprofil Android Gradle Plugin 8.6.0, Gradle 8.14.3, Kotlin Gradle Plugin 2.2.0, Java 17, compileSdk 36 und minSdk 26.

Das aktuelle React-Native-0.87-Kompatibilitätsprofil verwendet die von diesem Release erzeugten Versionen, darunter Android Gradle Plugin 9.2.1, Gradle 9.4.1, Kotlin Gradle Plugin 2.2.0 und Java 21. Behalten Sie für das aktuelle Profil die erzeugten Versionen bei.

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

Wrapper-Client konfigurieren und anzeigen

Der Wrapper unterstützt React Native 0.76 bis 0.87 mit aktivierter New Architecture. Stellen Sie nach der Paketinstallation und der Einrichtung der nativen Projekte credentialProvider aus Ihrer Host-Anwendung bereit.

credentialProvider wird von Ihrer Host-Anwendung bereitgestellt und gibt ein Objekt mit einem kurzlebigen Kundenidentitäts-JWT zurück. Verwenden Sie kein Support-API-Token im App-Bundle.

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

Eigenen Trigger und Sichtbarkeit des Inline-Widgets steuern

Setzen Sie visible={visible}, wenn eine Keep-alive-Route oder ein Overlay das Inline-Widget vorübergehend ausblendet. Der native Surface pausiert seine sichtbare Arbeit und behält Client, Sitzung und Entwurf. Verwenden Sie loadingBuilder für einen eigenen Vorbereitungszustand und errorBuilder oder onError für einen behebbaren Fehlerhinweis des Hosts.

Setzen Sie visible wieder auf true, wenn die Route zurückkehrt. Verwenden Sie denselben Client und montieren Sie nicht mehrere Inline-Flächen für eine Sitzung.

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

Navigation und Konto-Lebenszyklus verbinden

Rufen Sie closeWidget auf, wenn der Host-Bildschirm ausgehängt wird. Verwenden Sie resetSession zum bewussten Verwerfen einer Unterhaltung und logout vor einer Änderung von accountScope. Die native Engine verwaltet dauerhaften Zustand, Polling und Wiederholungen. JavaScript soll auf typisierte Ereignisse reagieren und keine zweite Warteschlange starten.

Der Wrapper zeigt denselben nativen UI-Vertrag wie die anderen mobilen SDKs. Lassen Sie reduceMotion weg, damit die Barrierefreiheitseinstellung des Host-Betriebssystems die Bewegung steuert.

Laden, Sichtbarkeit und Barrierefreiheit behandeln

Nutzen Sie Loading-Hooks oder typisierte Events für den Ladezustand des Hosts. Die Oberfläche zeigt Nachrichtenladen, Warten und Wiederholungen selbst an, damit kein zweiter Spinner das Eingabefeld überlagert.

Verbergen oder zeigen Sie die Oberfläche bei einer vorübergehenden Navigation und behalten Sie den Client. Das Widget respektiert die Systemoptionen für reduzierte Bewegung. Ein Entfernen oder Schließen verwirft weder Sitzung noch Entwurf.

1. Verwenden Sie beim erneuten Mounten denselben Client und feste Host-Abmessungen.
2. Verwenden Sie die Sichtbarkeitsfunktion für vorübergehendes Ausblenden und keine Session-Reset-Funktion.
3. Beenden Sie die Sitzung erst bei Logout oder einem bewussten Kontowechsel.

React-Native-Ablauf prüfen

1. Öffnen Sie das Widget aus einem sichtbaren React-Native-Bildschirm und prüfen Sie, dass das native Panel einmal angezeigt wird.
2. Abonnieren Sie Ereignisse und zeigen Sie einen Ladezustand auf Host-Ebene nur dann, wenn das SDK eine aktive Ladephase meldet.
3. Senden Sie mit stabilem idempotency key, verlieren Sie die Verbindung und rufen Sie flushOutbox auf, nachdem dasselbe Konto ein frisches Token erhalten hat. Erzeugen Sie für einen unsicheren Versand keinen neuen Schlüssel.