Using Native Libraries

Hosanna allows you to seamlessly interoperate with native Roku libraries (BrightScript .brs and .xml files). This enables you to leverage existing Roku components and third-party libraries within your Hosanna project.

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 '../../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, you must create "fake" versions of these libraries that mimic their interfaces and behaviors. Follow the patterns described in SG Nodes and API to create these emulator fakes.

Summary

• Copy .brs and .xml files into your project.
• Use hsconfig to ensure they are included in the build.
• Use CreateObject<YourInterface>() for type-safe instantiation.
• Observe node fields as needed.
• Create emulator fakes for development/testing.

This approach allows you to fully leverage native Roku libraries while maintaining the benefits of Hosanna's type safety and developer tooling.