Das DobroDesk NativeScript-SDK integrieren

Die NativeScript-Paketversion auswählen

Verwenden Sie eine abgestimmte NativeScript-Toolchain: NativeScript 8.9 mit passendem CLI und Core-Paketen der 8.9-Reihe oder NativeScript 9.x mit passenden CLI- und Core-Paketen der 9.x-Reihe. Der veröffentlichte Wrapper unterstützt NativeScript 8.9 bis 9.x. Kombinieren Sie kein 8.9-CLI mit 9.x-Core-Paketen und kein 9.x-CLI mit 8.9-Core-Paketen. Das folgende Beispiel verwendet den NativeScript-9.x-Webpack-Einstiegspunkt. Siehe die NativeScript-Hook-Dokumentation unter https://docs.nativescript.org/guide/hooks.

Das veröffentlichte DobroDesk-NativeScript-Paket 0.2.0 enthält den Webpack-Hook, Platform-Factories, das Android-Modul, das iOS-Podspec und die nativen XCFrameworks für den Wrapper.

Installieren Sie den Wrapper zusammen mit der passenden Version des gemeinsamen Protokollpakets. Halten Sie beide Versionen auf Mobile SDK 0.2.0 ausgerichtet. Das Paket enthält das Android-Modul, das iOS-Podspec und die nativen XCFrameworks für den Wrapper.

npm install @dobrodesk/nativescript-sdk@0.2.0 @dobrodesk/mobile-protocol@0.2.0

Den NativeScript-webpack-Einstieg beibehalten

NativeScript-9-Projekte erwarten eine webpack.config.js im Projektstamm. Wenn Ihre Vorlage sie nicht erstellt, fügen Sie die standardmäßige NativeScript-Konfiguration vor ns prepare hinzu, damit der Bundler die plattformspezifischen Paket-Einstiegspunkte auflösen kann.

const webpack = require("@nativescript/webpack");

module.exports = (env) => {
  webpack.init(env);
  return webpack.resolveConfig();
};

Gebündeltes Android-Repository registrieren

NativeScripts generiertes Android-Projekt liest diese Repository-Deklaration des Host-App-Moduls. Halten Sie den Pfad unter node_modules und kopieren Sie keine privaten nativen Quellen in die App. Das Android-Modul des Pakets löst daraus die gemeinsame Engine, den UI-Controller und die UI auf.

repositories {
  maven { url = uri("$rootDir/../../node_modules/@dobrodesk/nativescript-sdk/native/maven") }
}

Die Android-Untergrenze des Hosts setzen

Der NativeScript-Wrapper benötigt Android API 26 oder höher, compileSdk 36 und Java 17 für das native Modul. Behalten Sie die von Ihrer unterstützten NativeScript-Version erzeugten Kotlin- und Gradle-Versionen bei und setzen Sie minSdk und compile options in App_Resources/Android/app.gradle.

android {
  compileSdkVersion 36

  defaultConfig {
    minSdkVersion 26
  }

  compileOptions {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
  }
}

Den iOS-Host vorbereiten

Das veröffentlichte NativeScript-Paket enthält DobroDeskSDK.xcframework und DobroDeskUI.xcframework bereits entpackt unter ios/native/ios. Die platforms/ios/Podfile des Pakets verweist auf das DobroDeskNativeScript-Podspec, sodass NativeScript das Pod während ns prepare ios zusammenführt und CocoaPods ausführt. Für dieses Paket ist kein manuelles Entpacken von ZIP-Dateien erforderlich.

Setzen Sie vor der Plattformvorbereitung das iOS-Deployment-Target in App_Resources/iOS/build.xcconfig auf 15.1 oder höher.

npx ns prepare ios

# App_Resources/iOS/build.xcconfig
IPHONEOS_DEPLOYMENT_TARGET = 15.1;

Wrapper-Client konfigurieren und anzeigen

Der Wrapper unterstützt NativeScript 8.9 bis 9.x und verwendet beim Bündeln den von NativeScript gewählten Plattform-Einstiegspunkt. Stellen Sie nach der Paketinstallation und der Einrichtung des Android-Repositorys credentialProvider aus Ihrer Host-Anwendung bereit.

credentialProvider wird vom Host bereitgestellt und muss ein kurzlebiges Kundenidentitäts-JWT zurückgeben.

import { createDobroDeskNativeScriptClient } from "@dobrodesk/nativescript-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 = createDobroDeskNativeScriptClient(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 erstellt das Beispiel ein GridLayout mit fester Höhe und nimmt typisierte onError- und onLoadingChange-Callbacks des Hosts an, damit sich das Layout beim Laden nicht verschiebt.

Der eigene Button bleibt per Tastatur erreichbar und erhält aria-controls sowie aria-expanded. Verwenden Sie beim erneuten Mounten denselben Client, dieselbe Sitzung und denselben Entwurf.

createWidgetView gehört zum veröffentlichten Mobile-SDK-0.2.0-Paket. Mounten Sie es in der Host-View und rufen Sie release auf, wenn die View den Bildschirm verlässt, damit verspätete Arbeit keine andere Oberfläche öffnet oder freigibt.

import { GridLayout } from "@nativescript/core";
import type { DobroDeskNativeScriptClient } from "@dobrodesk/nativescript-sdk";
import type { DobroDeskSdkError } from "@dobrodesk/mobile-protocol";

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

export function createSupportPanel(
  client: DobroDeskNativeScriptClient,
  { onError }: SupportPanelOptions = {},
) {
  const supportHost = new GridLayout();
  supportHost.height = 560;
  supportHost.width = "100%";
  const supportView = client.createWidgetView({
    widget: { locale: "en", view: "home" },
    autoOpen: false,
    onError,
  });
  supportHost.addChild(supportView);
  return {
    host: supportHost,
    view: supportView,
    open: () => supportView.open(),
    close: () => supportView.close(),
    release: () => supportView.release(),
  };
}

Nur von einem sichtbaren Host anzeigen

iOS benötigt einen sichtbaren NativeScript Frame und Android eine sichtbare Activity. Wenn der Host im Hintergrund ist oder kein Frame vorhanden ist, schlägt die Anzeige mit einem typisierten Konfigurationsfehler fehl. Warten Sie auf das nächste sichtbare Lebenszyklusereignis, statt eine Schleife zu wiederholen.

Rufen Sie closeWidget auf, wenn die Host-Ansicht verworfen wird, resetSession beim Verwerfen einer Unterhaltung und logout vor Änderungen an accountScope. Lassen Sie reduceMotion weg, damit die nativen Systemeinstellungen für Barrierefreiheit maßgeblich bleiben.

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.

NativeScript-Ablauf prüfen

1. Öffnen Sie von einer sichtbaren Seite und prüfen Sie, dass das Widget der aktuellen iOS- oder Android-Navigationsoberfläche folgt.
2. Senden Sie eine Nachricht mit stabilem idempotency key, schicken Sie die App in den Hintergrund und stellen Sie sie wieder her. Prüfen Sie, dass flushOutbox die aufbewahrte Mutation erst nach der Autorisierung desselben Kontos wiederholt.
3. Versuchen Sie die Anzeige im Hintergrund und prüfen Sie, dass der Host einen behebbaren Fehler für den sichtbaren Zustand meldet, statt einen unsichtbaren Presenter zu erzeugen.