Integrate the DobroDesk NativeScript SDK

Choose the NativeScript package version

Use a matching NativeScript toolchain: NativeScript 8.9 with its matching 8.9 CLI and core packages or NativeScript 9.x with matching 9.x CLI and core packages. The published wrapper supports NativeScript 8.9 through 9.x. Do not combine the 8.9 CLI with 9.x core packages or use a 9.x CLI with 8.9 core packages. The example below uses the NativeScript 9.x webpack entrypoint. See the NativeScript hooks guide at https://docs.nativescript.org/guide/hooks.

The published DobroDesk NativeScript 0.2.0 package includes the Webpack hook, platform factories, Android module, iOS Podspec and native XCFrameworks required by the wrapper.

Install the wrapper together with the matching shared protocol package. Keep both versions aligned with Mobile SDK 0.2.0. The package includes the Android module, iOS Podspec and native XCFrameworks required by the wrapper.

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

Keep the NativeScript webpack entrypoint

NativeScript 9 projects expect a root webpack.config.js. If your generated template does not create it, add the standard NativeScript configuration before running ns prepare so platform-specific package entrypoints can be resolved by the bundle.

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

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

Register the bundled Android repository

NativeScript's generated Android project reads this host app-module repository declaration. Keep the path under node_modules and do not copy private native source into the app. The package's Android module resolves the shared engine, UI controller and UI from this repository.

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

Set the Android host floor

The NativeScript wrapper requires Android API 26 or newer, compileSdk 36 and Java 17 for the native module. Keep the NativeScript-generated Kotlin and Gradle versions for your supported NativeScript release, then set the application minSdk and compile options in App_Resources/Android/app.gradle.

android {
  compileSdkVersion 36

  defaultConfig {
    minSdkVersion 26
  }

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

Prepare the iOS host

The published NativeScript package already contains the extracted DobroDeskSDK.xcframework and DobroDeskUI.xcframework under ios/native/ios. Its platforms/ios/Podfile points to the DobroDeskNativeScript Podspec, so NativeScript can merge the pod and run CocoaPods during ns prepare ios. No manual ZIP extraction is required for this package.

Keep the iOS deployment target at 15.1 or newer in App_Resources/iOS/build.xcconfig before preparing the platform.

npx ns prepare ios

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

Configure and present the wrapper client

The wrapper supports NativeScript 8.9 through 9.x and uses the platform entry point selected by NativeScript at bundle time. After package installation and Android repository setup, provide the credentialProvider function from your host application.

The credentialProvider function is host-provided and must return a short-lived 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();

Render inline or use a custom trigger

createWidgetView returns a native ContentView that can live in a NativeScript layout. The example creates a bounded GridLayout and accepts the SDK's typed onError callback. Set autoOpen: false when a product button owns visibility and call open or close on the same view.

release removes the inline owner and native listeners without resetting the session or draft. Keep the same client when a Frame navigates away and returns, and do not create a second view while the first one is open.

createWidgetView is included in the published Mobile SDK 0.2.0 package. Mount it in the host view and call release when the view leaves the screen so late work cannot reopen or dispose another 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(),
  };
}

Present only from a foreground host

iOS requires a foreground NativeScript Frame and Android requires a foreground Activity. If the host is backgrounded or no frame is available, presentation fails with a typed configuration error. Wait for the next foreground lifecycle event instead of retrying in a loop.

Call closeWidget when the host view is disposed, resetSession when a conversation is discarded and logout before accountScope changes. Omit reduceMotion so native system accessibility settings remain in control.

Handle loading, detachment and accessibility

The native view renders message loading and retry states. Use client events for a page-level loading indicator, onLoadingChange for signed preparation and native mount work and onError for a recoverable host notice. Keep the ContentView mounted while a send is pending so the outbox can reconcile one idempotency key.

close changes visibility and release disposes the view. Neither action resets the session. NativeScript inherits reduced-motion and animation scale preferences from iOS or Android, while the host owns accessibility labels, focus order, safe areas and keyboard behavior.

1. Keep the view bounds stable and reuse the same client after a Frame remount.
2. Use close for temporary hiding and release only when the screen or account really ends.
3. Call logout and discard the client only for an intentional account change, then create a new client.

Verify the NativeScript flow

1. Open from a visible page and confirm that the widget follows the current iOS or Android navigation surface.
2. Send a message with a stable idempotency key, background the app and restore it. Confirm that flushOutbox retries the retained mutation only after the same account is authorized.
3. Attempt presentation from a background state and confirm the host reports a recoverable foreground error rather than creating an invisible presenter.