@roku-sdk/ads

⚠️ Development Notice: This package's interface may still change between releases. Pin the version and re-read the types after an upgrade.

Ad support for Roku SceneGraph TypeScript apps via the Roku Advertising Framework (RAF), across all three insertion modes:

| Mode | Command sequence | Needs | | --- | --- | --- | | CSAI — client-side insertion | getAds → showAds per break | adView + contentView | | SSAI — server-stitched insertion | getAds → stitchedAdsInit | contentView | | CSAS — client-side stitching | getAds → constructStitchedStream → renderStitchedStream | adView + contentMetadata; renders no app-owned Video |

<Ads> is a headless SceneGraph Task driven by writing props rather than by calling methods: wait for onAdsState to report "ready", set the data fields, set command last, then read the result off the matching callback.

Every string result is cleared to "none" before its real value, so from the second command onwards each handler is called with that sentinel first — treat it as "no result yet". Only the first command hides it, because the field already holds "none" and writing a field the value it already has notifies nobody. The same comparison is why re-issuing a command with the value it already has does nothing at all.

Mid-roll needs no cue-point loop in the app — the task observes contentView's position and calls RAF's getAds itself at each cue point, handing back the pods due now.

Requires bs_libs_required: "roku_ads_lib" in the app's manifestEntries; without it RAF never reports ready and every command is written into a void.

One worked example per mode lives in examples/ads.