Intégrer le SDK NativeScript DobroDesk

Choisir la version du package NativeScript

Utilisez une toolchain NativeScript cohérente : NativeScript 8.9 avec son CLI et ses paquets core de la série 8.9 ou NativeScript 9.x avec un CLI et des paquets core de la série 9.x. Le wrapper publié prend en charge NativeScript 8.9 à 9.x. Ne combinez pas le CLI 8.9 avec des paquets core 9.x ni un CLI 9.x avec des paquets core 8.9. L'exemple ci-dessous utilise le point d'entrée webpack de NativeScript 9.x. Consultez le guide des hooks NativeScript sur https://docs.nativescript.org/guide/hooks.

Le package DobroDesk NativeScript 0.2.0 publié contient le hook Webpack, les platform factories, le module Android, le Podspec iOS et les XCFrameworks natifs nécessaires au wrapper.

Installez le wrapper avec la version correspondante du package de protocole partagé. Gardez les deux versions alignées sur Mobile SDK 0.2.0. Le package contient le module Android, le Podspec iOS et les XCFrameworks natifs nécessaires au wrapper.

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

Conserver le point d'entrée webpack de NativeScript

Les projets NativeScript 9 attendent un webpack.config.js à la racine. Si votre modèle généré ne le crée pas, ajoutez la configuration NativeScript standard avant ns prepare afin que le bundler résolve les points d'entrée propres à chaque plateforme.

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

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

Enregistrer le dépôt Android inclus

Le projet Android généré par NativeScript lit cette déclaration de dépôt du module de l'application hôte. Gardez le chemin sous node_modules et ne copiez pas de code source natif privé dans l'application. Le module Android du package y résout le moteur partagé, le contrôleur UI et l'interface.

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

Définir le socle Android de l'hôte

Le wrapper NativeScript requiert Android API 26 ou version ultérieure, compileSdk 36 et Java 17 pour le module natif. Conservez les versions Kotlin et Gradle générées par votre version NativeScript prise en charge, puis définissez minSdk et compile options dans App_Resources/Android/app.gradle.

android {
  compileSdkVersion 36

  defaultConfig {
    minSdkVersion 26
  }

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

Préparer l'hôte iOS

Le package NativeScript publié contient déjà DobroDeskSDK.xcframework et DobroDeskUI.xcframework extraits dans ios/native/ios. Son platforms/ios/Podfile pointe vers le Podspec DobroDeskNativeScript, donc NativeScript peut intégrer le pod et exécuter CocoaPods pendant ns prepare ios. Ce package ne nécessite pas d'extraction manuelle des ZIP.

Avant de préparer la plateforme, gardez la cible de déploiement iOS à 15.1 ou plus dans App_Resources/iOS/build.xcconfig.

npx ns prepare ios

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

Configurer et présenter le client wrapper

Le wrapper prend en charge NativeScript 8.9 à 9.x et utilise le point d'entrée de plateforme choisi par NativeScript lors du bundling. Après l'installation du package et la configuration du dépôt Android, fournissez credentialProvider depuis votre application hôte.

credentialProvider est fourni par l'hôte et doit renvoyer un JWT d'identité client de courte durée.

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

Utiliser un déclencheur personnalisé ou une surface intégrée

Utilisez launcher: hidden lorsque votre application contrôle le déclencheur. L'exemple crée un GridLayout avec une hauteur stable et accepte les callbacks typés onError et onLoadingChange de l'hôte afin d'éviter les changements de mise en page pendant le chargement.

Le bouton personnalisé doit rester accessible au clavier et exposer aria-controls ainsi que aria-expanded. Lors d'un nouveau montage, réutilisez le même client, la même session et le même brouillon.

createWidgetView fait partie du package Mobile SDK 0.2.0 publié. Montez-le dans la vue de l'hôte et appelez release lorsque la vue quitte l'écran afin qu'un travail tardif n'ouvre ou ne libère pas une autre surface.

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

Présenter uniquement depuis un hôte au premier plan

iOS exige un NativeScript Frame au premier plan et Android une Activity au premier plan. Si l'hôte est en arrière-plan ou qu'aucun frame n'est disponible, la présentation échoue avec une erreur de configuration typée. Attendez le prochain événement de cycle au premier plan au lieu de réessayer en boucle.

Appelez closeWidget lorsque la vue hôte est détruite, resetSession lorsqu'une conversation est abandonnée et logout avant de changer accountScope. Omettez reduceMotion pour laisser les réglages d'accessibilité du système contrôler le mouvement.

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 NativeScript

1. Ouvrez depuis une page visible et confirmez que le widget suit la surface de navigation iOS ou Android actuelle.
2. Envoyez un message avec un idempotency key stable, mettez l'app en arrière-plan puis restaurez-la. Confirmez que flushOutbox réessaie la mutation conservée uniquement après l'autorisation du même compte.
3. Tentez une présentation en arrière-plan et confirmez que l'hôte signale une erreur récupérable de premier plan plutôt que de créer un presenter invisible.