Using Native Libraries

Hosanna apps can call platform-native libraries when shared TypeScript needs device services, media SDKs, analytics, store APIs, or platform UI. First check whether Hosanna already exposes the capability as a typed system service. Add a custom adapter only when the built-in contract does not cover the use case.

Start With Platform Capabilities

Do not infer support from the platform name. Resolve the platform capability contract and handle unsupported or unavailable results. A capability may exist on one Apple or Android target and return an explicit unsupported result on Web or Roku.

Hosanna currently registers typed services for:

IoC key	Shared interface	Typical use
notificationManager	INotificationManager	Permission, local notifications, remote registration, and events
nativeSheetsManager	INativeSheetsManager	Action and share sheets
castManager	ICastManager	Availability, picker, session start, and stop
purchaseManager	IPurchaseManager	Products, purchases, restore, and purchase flows
nativeAuthManager	INativeAuthManager	Web authentication and credential state
downloadManager	INativeDownloadManager	Native-managed downloads

The interfaces and ServiceResult contract live in @hs-src/hosanna-bridge-lib/system-services.

import type {
  INotificationManager,
} from '@hs-src/hosanna-bridge-lib/system-services';

const notifications =
  this.resolveService<INotificationManager>('notificationManager');

const result = notifications.getPermissionStatus();

if (!result.ok) {
  // Treat unsupported, unavailable, cancelled, and native failures explicitly.
  return;
}

Use the native-system rigs in hosanna-ui-samples-public/src/hosanna-ui-examples/rigs/native-system/ as executable examples. They probe service availability separately from interactive operations that can display platform UI, request permission, start authentication, or initiate a purchase.

Adding a Custom Adapter

1. Add the native dependency to the platform project.
2. Create a typed TypeScript adapter for the shared app to call.
3. Bind the adapter during platform initialization through the IoC service map or a narrow bridge API.
4. Provide an unsupported implementation or test fake for platforms that do not implement it.
5. Validate the real integration on hardware before release.

Roku Libraries

Keep third-party .brs and .xml files in a Roku-owned source directory and copy them with the selected Roku hsconfig. Describe each exposed SceneGraph node with a typed interface, then create or observe it through the same SceneGraph APIs used by the vendor library.

Native Roku code does not execute in the browser runtime. Bind a browser fake through the same app-level interface when shared UI development needs the integration, and validate the actual library on Roku hardware.

Hosanna also supports two library-authoring models:

• Roku Component Libraries expose separately hosted SceneGraph nodes at runtime.
• Roku Code Libraries compile copied BrightScript modules for build-time integration.

Choose the delivery model deliberately; they have different initialization, versioning, and consumer contracts.

Apple And Android Libraries

Apple integrations belong in the Apple platform project; Android integrations belong in the Android platform project. Expose only a small app-level contract to shared code.

• Keep Swift/Objective-C dependencies in the iOS or tvOS host.
• Keep Kotlin/Java dependencies in the Android or Android TV host.
• Use the same TypeScript interface for phone and TV variants only when the native behavior is genuinely the same.
• Exercise the adapter in a simulator first where supported, then verify permissions, lifecycle, focus/input, playback, and failure handling on physical hardware.
• Never put vendor credentials in the shared adapter or tracked build config.

Summary

• Prefer Hosanna's typed native system services when they cover the capability.
• Keep additional native SDKs inside the platform project that owns them.
• Expose only typed, app-level capabilities to shared Hosanna code.
• Use dependency injection or platform initialization to bind the correct implementation.
• Return explicit unsupported results or provide test doubles outside the owning platform.
• Validate native behavior on real target hardware.

This approach lets you use platform-native capability while maintaining Hosanna's type safety, source visibility, and shared app architecture.