Using Native Libraries

Hosanna apps can interoperate with platform-native libraries when shared TypeScript code needs access to device services, media SDKs, analytics SDKs, store APIs, or platform-specific UI. Keep native code behind small adapters so application screens remain portable across Roku, Apple TV, Android TV, Samsung TV, iOS, Android, and Web.

General Pattern

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 through platform-specific initialization, dependency injection, or a narrow bridge API.
4. Provide a Web or test fake when you need to develop without the target device.
5. Validate the real integration on hardware before release.

How to Use Native Roku Libraries

1. Copy the Library Files Copy the required .brs and .xml files from the native Roku library into your project directory.

2. Configure Static File Copying To ensure these files are included in your build, add an entry to your hsconfig file. For example:

   // ...existing hsconfig...
   "staticFiles": [
     { "src": "raw/roku-libs/youbora", "dest": "./youbora" }
   ],
   // ...existing hsconfig...

   This will copy the contents of raw/roku-libs/youbora into the build output under ./youbora.

3. Use CreateObject as Usual In Hosanna, CreateObject is generic, allowing you to specify a TypeScript interface that describes the node's properties or the shape of any BrightScript class (i.e., its members). This provides type safety and better developer experience.

   For example, define an interface for your library:

   // ...existing code...
   import { JsonData } from '@hs-src/hosanna-ui/async/AsyncApi';
   import { ISGNNode, ISGNTask, TaskControl } from './sg-api';
   
   /**
    * `ISGNYBPluginGeneric` defines a generic interface for SGN plugins.
    * It includes properties for managing video players, events, options, logging, and monitoring.
    */
   export interface ISGNYBPluginGeneric extends ISGNTask {
     videoplayer?: ISGNNode;
     event?: JsonData;
     options?: JsonData;
     updateplayer?: JsonData;
     logging?: boolean;
     adevent?: JsonData;
     imaadevent?: JsonData;
     session?: JsonData;
     productAnalytics?: JsonData;
     pingTime?: number;
     monitoring?: boolean;
   }
   
   /**
    * `ISGNYBPluginRokuVideo` extends `ISGNYBPluginGeneric` to include properties specific to Roku video plugins.
    * It adds support for task state and task control.
    */
   export interface ISGNYBPluginRokuVideo extends ISGNYBPluginGeneric {
     taskState?: string;
     control?: TaskControl;
   }
   // ...existing code...

   Then, instantiate your native library node with type safety:

   const plugin = CreateObject<ISGNYBPluginRokuVideo>('roSGNode', 'YouboraPlugin');

Observing Node Fields

If the third-party API requires you to observe fields on nodes (e.g., for event handling or state changes), you can use Hosanna's node observation mechanisms. This works the same way as with any other SG node.

Using Native Libraries in the Emulator

Native Roku libraries cannot run in the Hosanna emulator. If you wish to use them during development, create emulator fakes that mimic their interfaces and behavior, then bind those fakes through the same typed SceneGraph interfaces your device build uses.

Apple TV Native Libraries

Apple TV integrations should live in the Apple platform project and be exposed to shared Hosanna code through typed adapters. Use this path for tvOS media SDKs, analytics SDKs, authentication helpers, store APIs, and device services.

For now, keep the shared contract small:

• Define a TypeScript interface for the capability the app needs.
• Implement the real adapter in the Apple TV target.
• Register the adapter during platform initialization.
• Use a Web fake for local development and tests.
• Validate lifecycle, focus/input behavior, playback, and error handling on an Apple TV device.

Android TV And Android Native Libraries

Android TV and Android integrations should live in the Android platform project and be exposed through typed adapters. Use this path for Kotlin/Java SDKs, media players, analytics, authentication, billing, storage, and device APIs.

For now, keep the integration structure simple:

• Add the SDK or native module to the Android project.
• Wrap the platform API in an adapter with a stable TypeScript-facing interface.
• Register the adapter during Android platform initialization.
• Use a Web fake or test double when developing shared app screens.
• Validate emulator behavior first, then verify on physical Android TV and Android devices.

iOS Native Libraries

iOS integrations should live in the iOS platform project and be exposed to shared Hosanna code through typed adapters. Use this path for iOS SDKs, media services, analytics, authentication, in-app purchase, storage, and device APIs.

For now, use the same adapter pattern:

• Add the SDK or native module to the iOS project.
• Define the shared TypeScript interface the app will call.
• Implement the real iOS adapter in the platform target.
• Register the adapter during iOS platform initialization.
• Validate simulator behavior, then test on physical iPhone and iPad hardware.

Summary

• Keep 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.
• Provide Web fakes or test doubles for local development.
• 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.