Інтегруйте DobroDesk NativeScript SDK

Оберіть версію NativeScript-пакета

Використовуйте узгоджений NativeScript toolchain: NativeScript 8.9 із відповідними CLI та core-пакетами серії 8.9 або NativeScript 9.x із відповідними CLI та core-пакетами серії 9.x. Опублікована обгортка підтримує NativeScript від 8.9 до 9.x. Не поєднуйте CLI 8.9 із core-пакетами 9.x або CLI 9.x із core-пакетами 8.9. У прикладі нижче використовується webpack entrypoint NativeScript 9.x. Дивіться документацію NativeScript про hooks: https://docs.nativescript.org/guide/hooks.

Опублікований пакет DobroDesk NativeScript 0.2.0 містить Webpack hook, platform factories, Android-модуль, iOS Podspec і нативні XCFrameworks, потрібні обгортці.

Встановіть обгортку разом із відповідною версією спільного пакета протоколу. Узгоджуйте обидві версії з Mobile SDK 0.2.0. Пакет містить Android-модуль, iOS Podspec і нативні XCFrameworks, потрібні обгортці.

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

Збережіть webpack entrypoint NativeScript

Проєкти NativeScript 9 очікують root webpack.config.js. Якщо згенерований шаблон його не створив, додайте стандартну конфігурацію NativeScript до запуску ns prepare, щоб бандлер міг вибрати платформні entrypoint-и пакета.

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

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

Зареєструйте bundled Android-репозиторій

Згенерований Android-проєкт NativeScript читає цю декларацію репозиторію модуля застосунку хоста. Залиште шлях під node_modules і не копіюйте приватний нативний код у застосунок. Android-модуль пакета знаходить тут базовий рушій, UI-контролер і UI.

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

Задайте Android floor хоста

NativeScript-обгортка вимагає Android API 26 або новіший, compileSdk 36 і Java 17 для нативного модуля. Залиште Kotlin і Gradle, згенеровані вашою підтримуваною версією NativeScript, а minSdk і compile options задайте в App_Resources/Android/app.gradle.

android {
  compileSdkVersion 36

  defaultConfig {
    minSdkVersion 26
  }

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

Підготуйте iOS host

Опублікований NativeScript-пакет уже містить розпаковані DobroDeskSDK.xcframework і DobroDeskUI.xcframework у ios/native/ios. Його platforms/ios/Podfile посилається на DobroDeskNativeScript Podspec, тому NativeScript підключає pod і запускає CocoaPods під час ns prepare ios. Для цього пакета вручну розпаковувати ZIP не потрібно.

Перед підготовкою платформи залиште deployment target iOS 15.1 або новіший у App_Resources/iOS/build.xcconfig.

npx ns prepare ios

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

Налаштуйте й відкрийте wrapper client

Обгортка підтримує NativeScript від 8.9 до 9.x і під час збирання використовує платформну точку входу, яку вибирає NativeScript. Після встановлення пакета й налаштування Android-репозиторію надайте credentialProvider зі свого застосунку хоста.

Функція credentialProvider надається хостом і має повертати короткоживучий customer identity JWT.

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

Відрендерте inline або використайте власний тригер

createWidgetView повертає нативний ContentView для NativeScript layout. Приклад створює GridLayout зі сталою висотою та приймає типізований callback onError від хоста. Використовуйте autoOpen: false, коли видимістю керує кнопка продукту.

release прибирає inline-власника без скидання сесії чи чернетки. Зберігайте той самий client під час навігації Frame.

createWidgetView входить до опублікованого пакета Mobile SDK 0.2.0. Монтуйте його у view хоста й викликайте release, коли view залишає екран, щоб пізня робота не відкрила або не звільнила чужу поверхню.

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

Відкривайте лише з foreground-хоста

iOS вимагає foreground NativeScript Frame, а Android — foreground Activity. Якщо хост у фоні або frame недоступний, відкриття завершується типізованою помилкою конфігурації. Дочекайтеся наступної foreground-події життєвого циклу замість циклу повторних спроб.

Викликайте closeWidget, коли view хоста знищується, resetSession після відкидання розмови та logout перед зміною accountScope. Не задавайте reduceMotion, щоб системні налаштування доступності залишалися керівними.

Керуйте завантаженням, від'єднанням і доступністю

Нативний ContentView показує завантаження та повтори. Використовуйте події client для стану сторінки, onLoadingChange для підготовки підписаної ідентичності та монтування native view і onError для відновлюваного повідомлення хоста.

close змінює видимість, а release звільняє view без скидання сесії. Поважайте системні reduced-motion та animation scale, а host залишайте відповідальним за доступні назви, safe area й клавіатуру.

1. Зберігайте сталі bounds і повторно використовуйте той самий client після remount Frame.
2. Використовуйте close для тимчасового приховування, а release — лише коли view або акаунт справді завершені.
3. Викликайте logout і відкидайте client лише під час навмисної зміни акаунта.

Перевірте NativeScript-флоу

1. Відкрийте віджет із видимої сторінки й перевірте, що він використовує поточну навігаційну поверхню iOS або Android.
2. Надішліть повідомлення зі стабільним idempotency key, відправте застосунок у фон і відновіть його. Перевірте, що flushOutbox повторює збережену мутацію лише після авторизації того самого акаунта.
3. Спробуйте відкрити віджет у фоні й перевірте, що хост повідомляє про відновлювану помилку foreground, а не створює невидимий presenter.