Integrar o SDK NativeScript DobroDesk

Escolher a versão do pacote NativeScript

Use uma toolchain NativeScript correspondente: NativeScript 8.9 com o CLI e os pacotes core correspondentes da série 8.9 ou NativeScript 9.x com CLI e pacotes core correspondentes da série 9.x. O wrapper publicado suporta NativeScript 8.9 a 9.x. Não combine o CLI 8.9 com pacotes core 9.x nem um CLI 9.x com pacotes core 8.9. O exemplo seguinte usa o ponto de entrada webpack do NativeScript 9.x. Consulte o guia de hooks do NativeScript em https://docs.nativescript.org/guide/hooks.

O pacote publicado DobroDesk NativeScript 0.2.0 inclui o hook do Webpack, as platform factories, o módulo Android, o Podspec iOS e os XCFrameworks nativos necessários ao wrapper.

Instale o wrapper com a versão correspondente do pacote de protocolo partilhado. Mantenha ambas as versões alinhadas com o Mobile SDK 0.2.0. O pacote inclui o módulo Android, o Podspec iOS e os XCFrameworks nativos necessários ao wrapper.

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

Manter o ponto de entrada webpack do NativeScript

Os projetos NativeScript 9 esperam um webpack.config.js na raiz. Se o modelo gerado não o criar, adicione a configuração padrão do NativeScript antes de executar ns prepare para que o bundler resolva os pontos de entrada específicos da plataforma.

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

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

Registar o repositório Android incluído

O projeto Android gerado pelo NativeScript lê esta declaração de repositório do módulo da aplicação host. Mantenha o caminho em node_modules e não copie código nativo privado para a app. O módulo Android do pacote resolve aqui o motor partilhado, o controlador de UI e a UI.

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

Definir o nível Android do host

O wrapper NativeScript requer Android API 26 ou posterior, compileSdk 36 e Java 17 para o módulo nativo. Mantenha as versões de Kotlin e Gradle geradas pela versão NativeScript suportada e defina minSdk e compile options em App_Resources/Android/app.gradle.

android {
  compileSdkVersion 36

  defaultConfig {
    minSdkVersion 26
  }

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

Preparar o host iOS

O pacote NativeScript publicado já contém DobroDeskSDK.xcframework e DobroDeskUI.xcframework extraídos em ios/native/ios. O seu platforms/ios/Podfile aponta para o Podspec DobroDeskNativeScript, por isso o NativeScript pode integrar o pod e executar CocoaPods durante ns prepare ios. Este pacote não requer extração manual dos ZIP.

Antes de preparar a plataforma, mantenha o deployment target do iOS em 15.1 ou posterior no App_Resources/iOS/build.xcconfig.

npx ns prepare ios

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

Configurar e apresentar o cliente wrapper

O wrapper suporta NativeScript 8.9 a 9.x e usa o ponto de entrada da plataforma selecionado pelo NativeScript no bundle. Depois de instalar o pacote e configurar o repositório Android, forneça credentialProvider a partir da sua aplicação host.

credentialProvider é fornecido pelo host e deve devolver um JWT de identidade do cliente de curta duração.

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 um acionador personalizado ou uma superfície integrada

Use launcher: hidden quando o seu aplicativo controla o acionador. O exemplo cria um GridLayout com altura estável e aceita callbacks tipados onError e onLoadingChange do host para evitar mudanças no layout durante o carregamento.

O botão personalizado deve ser acessível pelo teclado e expor aria-controls e aria-expanded. Ao montar novamente, reutilize o mesmo cliente, a mesma sessão e o mesmo rascunho.

createWidgetView faz parte do pacote publicado do Mobile SDK 0.2.0. Monte-o na view do host e chame release quando a view sair do ecrã para evitar que trabalho atrasado abra ou liberte outra superfície.

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

Apresentar apenas a partir de um host em primeiro plano

O iOS exige um NativeScript Frame em primeiro plano e o Android uma Activity em primeiro plano. Se o host estiver em segundo plano ou não existir um frame, a apresentação falha com um erro de configuração tipado. Aguarde o próximo evento de ciclo em primeiro plano em vez de repetir num loop.

Chame closeWidget quando a vista do host for eliminada, resetSession quando uma conversa for descartada e logout antes de alterar accountScope. Omita reduceMotion para manter o controlo das definições de acessibilidade do sistema.

Tratar carregamento, visibilidade e acessibilidade

Use hooks de carregamento ou eventos tipados para o estado da tela hospedeira. A superfície mostra o carregamento das mensagens, a espera e as tentativas novamente para evitar um segundo indicador sobre o campo de entrada.

Oculte ou mostre a superfície durante uma navegação temporária mantendo o cliente. O widget respeita as preferências do sistema para reduzir movimento. Remover ou fechar a vista não descarta a sessão nem o rascunho.

1. Ao montar novamente, reutilize o mesmo cliente e dimensões estáveis do contêiner.
2. Use a função de visibilidade para ocultar temporariamente, sem redefinir a sessão.
3. Finalize a sessão apenas ao sair ou trocar de conta de forma intencional.

Verificar o fluxo NativeScript

1. Abra a partir de uma página visível e confirme que o widget segue a superfície de navegação atual do iOS ou Android.
2. Envie uma mensagem com idempotency key estável, envie a app para segundo plano e restaure-a. Confirme que flushOutbox repete a mutação retida apenas depois de autorizar a mesma conta.
3. Tente apresentar em segundo plano e confirme que o host comunica um erro recuperável de primeiro plano em vez de criar um presenter invisível.