Integra el SDK NativeScript de DobroDesk

Elige la versión del paquete NativeScript

Usa una toolchain de NativeScript emparejada: NativeScript 8.9 con su CLI y paquetes core de la serie 8.9 o NativeScript 9.x con CLI y paquetes core de la serie 9.x. El wrapper publicado admite NativeScript de 8.9 a 9.x. No combines el CLI 8.9 con paquetes core 9.x ni un CLI 9.x con paquetes core 8.9. El ejemplo siguiente usa el punto de entrada de webpack de NativeScript 9.x. Consulta la guía de hooks de NativeScript en https://docs.nativescript.org/guide/hooks.

El paquete publicado DobroDesk NativeScript 0.2.0 incluye el hook de Webpack, las platform factories, el módulo Android, el Podspec de iOS y los XCFrameworks nativos que necesita el wrapper.

Instala el wrapper junto con la versión correspondiente del paquete de protocolo compartido. Mantén ambas versiones alineadas con Mobile SDK 0.2.0. El paquete incluye el módulo Android, el Podspec de iOS y los XCFrameworks nativos que necesita el wrapper.

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

Conserva el punto de entrada webpack de NativeScript

Los proyectos NativeScript 9 esperan un webpack.config.js en la raíz. Si la plantilla generada no lo crea, añade la configuración estándar de NativeScript antes de ejecutar ns prepare para que el bundler resuelva los puntos de entrada específicos de cada plataforma.

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

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

Registra el repositorio Android incluido

El proyecto Android generado por NativeScript lee esta declaración del repositorio del módulo de la aplicación host. Mantén la ruta bajo node_modules y no copies código nativo privado a la aplicación. El módulo Android del paquete resuelve desde aquí el motor compartido, el controlador de UI y la UI.

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

Establece el nivel mínimo del host Android

El wrapper NativeScript requiere Android API 26 o posterior, compileSdk 36 y Java 17 para el módulo nativo. Conserva las versiones de Kotlin y Gradle generadas por tu versión de NativeScript compatible y establece minSdk y compile options en App_Resources/Android/app.gradle.

android {
  compileSdkVersion 36

  defaultConfig {
    minSdkVersion 26
  }

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

Prepara el host iOS

El paquete NativeScript publicado ya contiene DobroDeskSDK.xcframework y DobroDeskUI.xcframework extraídos en ios/native/ios. Su platforms/ios/Podfile apunta al Podspec DobroDeskNativeScript, así que NativeScript puede integrar el pod y ejecutar CocoaPods durante ns prepare ios. Este paquete no requiere extraer ZIP manualmente.

Antes de preparar la plataforma, mantén el deployment target de iOS en 15.1 o posterior dentro de App_Resources/iOS/build.xcconfig.

npx ns prepare ios

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

Configura y presenta el cliente wrapper

El wrapper admite NativeScript de 8.9 a 9.x y usa el punto de entrada de plataforma que NativeScript selecciona al empaquetar. Después de instalar el paquete y configurar el repositorio Android, proporciona credentialProvider desde tu aplicación host.

credentialProvider lo proporciona el host y debe devolver un JWT de identidad del cliente de corta duración.

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

Usar un disparador propio o una superficie integrada

Usa launcher: hidden cuando tu aplicación controla el disparador. El ejemplo crea un GridLayout con una altura estable y acepta callbacks tipados onError y onLoadingChange del host para que el diseño no salte durante la carga.

El botón propio debe ser accesible con teclado y exponer aria-controls y aria-expanded. Al volver a montar, reutiliza el mismo cliente, la misma sesión y el mismo borrador.

createWidgetView forma parte del paquete publicado de Mobile SDK 0.2.0. Móntalo en la vista del host y llama a release cuando la vista salga de la pantalla para evitar que el trabajo tardío abra o libere otra superficie.

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

Presenta solo desde un host en primer plano

iOS requiere un NativeScript Frame en primer plano y Android una Activity en primer plano. Si el host está en segundo plano o no hay un frame disponible, la presentación falla con un error de configuración tipado. Espera al siguiente evento de ciclo en primer plano en vez de reintentar en un bucle.

Llama a closeWidget cuando se elimine la vista host, a resetSession al descartar una conversación y a logout antes de cambiar accountScope. Omite reduceMotion para mantener el control de los ajustes de accesibilidad del sistema.

Gestionar carga, visibilidad y accesibilidad

Usa los hooks de carga o los eventos tipados para el estado de la pantalla anfitriona. La superficie muestra por sí misma la carga de mensajes, la espera y los reintentos para evitar un segundo spinner sobre el campo de entrada.

Oculta o muestra la superficie cuando una ruta cambia temporalmente y conserva el cliente. El widget respeta las preferencias del sistema para reducir movimiento. Quitar o cerrar la vista no descarta la sesión ni el borrador.

1. Al volver a montar, reutiliza el mismo cliente y dimensiones estables del contenedor.
2. Usa la función de visibilidad para ocultar temporalmente, no una función de reinicio de sesión.
3. Finaliza la sesión solo al cerrar sesión o cambiar de cuenta de forma intencionada.

Verifica el flujo de NativeScript

1. Ábrelo desde una página visible y confirma que el widget sigue la superficie de navegación actual de iOS o Android.
2. Envía un mensaje con un idempotency key estable, pasa la app al segundo plano y restáurala. Confirma que flushOutbox reintenta la mutación retenida solo después de autorizar la misma cuenta.
3. Intenta presentarlo en segundo plano y confirma que el host informa de un error recuperable de primer plano en vez de crear un presenter invisible.