Das DobroDesk Capacitor-SDK integrieren

Veröffentlichte Capacitor-Pakete installieren und synchronisieren

Für einen neuen Host initialisieren Sie Capacitor einmal, installieren Sie passende Capacitor-Plattformpakete sowie den DobroDesk-Wrapper und das gemeinsame Protokollpaket in derselben Release-Version. Fügen Sie jede native Plattform einmal hinzu und synchronisieren Sie anschließend die Projekte.

# Run once for a new host.
npx cap init "Your app" com.example.app --web-dir=www

npm install @capacitor/core@8.5.3 @capacitor/cli@8.5.3 @capacitor/ios@8.5.3 @capacitor/android@8.5.3 @dobrodesk/capacitor-sdk@0.2.0 @dobrodesk/mobile-protocol@0.2.0
npx cap add ios --packagemanager CocoaPods
npx cap add android
npx cap sync

Gebündeltes Android-Repository registrieren

Fügen Sie den lokalen Maven-Pfad des Capacitor-Wrappers aus den Android-Hosteinstellungen hinzu. Der Wrapper wendet org.jetbrains.kotlin.android ohne Versionswahl an. Deklarieren Sie deshalb die Kotlin- und Android-Plugins vor den generierten Include-Zeilen. Das getestete minimale Capacitor-6.2.1-Hostprofil verwendet Android Gradle Plugin 8.13.2, Kotlin Gradle Plugin 2.2.0, Gradle 8.14.3 und JDK 17. Der aktuelle generierte Capacitor-8.5.3-Host verwendet AGP 8.13.0, Kotlin 2.2.20 und JDK 21. Behalten Sie die von der installierten Capacitor-Version erzeugten Versionen bei. PREFER_SETTINGS hält das Repository des offiziellen Capacitor-Android-Moduls kompatibel, während die DobroDesk-Artefakte aus dem installierten Paket aufgelöst werden.

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

plugins {
    id 'com.android.application' version '8.13.0' apply false
    id 'com.android.library' version '8.13.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.2.20' apply false
}

import org.gradle.api.initialization.resolve.RepositoriesMode

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

// Keep the generated include and apply-from lines below this block.

Native Plattformanforderungen festlegen

Der veröffentlichte Wrapper benötigt iOS 15.1 oder höher und Android API 26 oder höher. Beide getesteten Android-Profile verwenden Compile SDK 36 und minSdk 26. Das minimale Capacitor-6.2.1-Profil verwendet JDK 17. Setzen Sie für dieses Profil distributionUrl in android/gradle/wrapper/gradle-wrapper.properties auf https://services.gradle.org/distributions/gradle-8.14.3-all.zip. Aktuelle Capacitor-8.5.3-Hosts verwenden JDK 21 mit dem erzeugten kompatiblen Wrapper und Versionssatz. Setzen Sie das iOS-Deployment-Target vor pod install und erhöhen Sie minSdkVersion im generierten Android-Projekt von 24 auf 26.

# ios/App/Podfile
platform :ios, "15.1"

# android/variables.gradle
minSdkVersion = 26
compileSdkVersion = 36

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

Nativen Wrapper konfigurieren und anzeigen

Der Wrapper unterstützt Capacitor 6 bis 8. Stellen Sie nach der Paketinstallation, der Synchronisierung der nativen Projekte und der Einrichtung des Repositorys credentialProvider aus Ihrer Host-Anwendung bereit.

Der Web-Bildschirm des Hosts bleibt eine normale Capacitor-WebView, aber Widget und Transport von DobroDesk sind nativ. Laden Sie den Web-Renderer des Widgets nicht als Ersatz für diese Integration in die WebView.

import { DobroDeskCapacitorClient } from "@dobrodesk/capacitor-sdk";
import type { DobroDeskSdkConfig } from "@dobrodesk/mobile-protocol";

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

const client = new DobroDeskCapacitorClient(config);
await client.presentWidget();

Eigenen Trigger oder Inline-Fläche verwenden

Verwenden Sie launcher: hidden, wenn Ihre Anwendung den Trigger besitzt. Für eine Inline-Fläche braucht der Host vor dem Mounten feste Breite und Höhe, damit sich das Layout beim Laden nicht verschiebt.

Der eigene Button bleibt per Tastatur erreichbar und erhält aria-controls sowie aria-expanded. Übergeben Sie den typisierten onError-Callback, wenn der Host eine eigene Wiederherstellungsanzeige braucht. Die Rückgabefunktion des Beispiels entfernt den Button-Listener und ruft dispose auf, ohne Sitzung oder Entwurf zurückzusetzen.

mountWidget gehört zum veröffentlichten Mobile-SDK-0.2.0-Paket. Verwenden Sie es für eine begrenzte native Fläche und rufen Sie await handle.dispose() auf, wenn der Host den Container entfernt.

import type {
  DobroDeskCapacitorClient,
  DobroDeskEmbeddedWidget,
} from "@dobrodesk/capacitor-sdk";

type SupportPanelOptions = Readonly<{
  onError?: (error: unknown) => void;
}>;

export async function mountSupportPanel(
  client: DobroDeskCapacitorClient,
  { onError }: SupportPanelOptions = {},
) {
  const supportSlot = document.querySelector<HTMLElement>("#support-slot");
  const helpButton = document.querySelector<HTMLButtonElement>("#help-button");
  if (
    !supportSlot ||
    !helpButton ||
    !supportSlot.isConnected ||
    !helpButton.isConnected
  ) {
    throw new Error("Connect #support-slot and #help-button before mounting");
  }
  Object.assign(supportSlot.style, { width: "100%", height: "560px" });
  helpButton.setAttribute("aria-controls", "support-slot");
  let visible = true;
  let mountedHandle: DobroDeskEmbeddedWidget | undefined;
  const toggle = () => {
    visible = !visible;
    mountedHandle?.setVisible(visible);
    helpButton.setAttribute("aria-expanded", String(visible));
  };
  const onClose = () => {
    visible = false;
    helpButton.setAttribute("aria-expanded", "false");
  };
  helpButton.addEventListener("click", toggle);
  try {
    mountedHandle = await client.mountWidget(
      supportSlot,
      { locale: "en", view: "home" },
      { onClose, onError },
    );
    mountedHandle.setVisible(true);
    helpButton.setAttribute("aria-expanded", "true");
  } catch (error) {
    helpButton.removeEventListener("click", toggle);
    onError?.(error);
    throw error;
  }
  if (!mountedHandle) throw new Error("Support widget did not mount");
  const handle = mountedHandle;
  return {
    handle,
    dispose: async () => {
      helpButton.removeEventListener("click", toggle);
      await handle.dispose();
    },
  };
}

Hybrid- und native Lebenszyklen getrennt halten

Der vom Host bereitgestellte credentialProvider muss einen Backend-Endpunkt aufrufen, der ein kurzlebiges Kundenidentitäts-JWT zurückgibt. Er darf weder Support-API-Token noch Signier-Geheimnis im Web-Bundle offenlegen. Rufen Sie closeWidget beim Zerstören der Host-Route, resetSession beim Verwerfen der Unterhaltung und logout vor einem Kontowechsel auf.

Der native Presenter beachtet die Systemeinstellung für reduzierte Bewegung, wenn kein Override geliefert wird. Halten Sie Host-Seitenübergänge getrennt, damit ein WebView-Routenwechsel kein zweites natives Widget erzeugt.

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.

Capacitor-Ablauf prüfen

1. Führen Sie nach npx cap sync npx cap doctor aus und öffnen Sie dann das Widget aus dem Web-Bildschirm. Prüfen Sie, dass die Anzeige nativ ist und kein zweites Web-Widget-iframe erscheint.
2. Prüfen Sie start, resume, send mit stabilem idempotency key, refresh und flushOutbox während wechselnder Netzwerkverfügbarkeit.
3. Rufen Sie logout vor dem Wechsel der signierten Kundin oder des signierten Kunden auf und prüfen Sie, dass die nächste Person die vorherige native Sitzung nicht übernimmt.