Skip to main content

Native Development Android TV

Hosanna Android phone and TV targets share the app-owned Gradle project under platforms/android, while using separate application IDs, resources, launch targets, and Hosanna compiler projects where the app requires them. Treat that native project as production source: HST validates and drives it, but Android Studio and Gradle remain the authority for signing and release artifacts.

Validate the Project​

Run the lightweight checks before opening Android Studio:

npx hst native:prepare android-tv
npx hst native:doctor android-tv
npx hst target:list android-tv --target sim
npx hst target:list android-tv --target device

native:prepare validates the inferred native configuration without writing files. native:doctor checks the installed framework reference, app-owned files, identifiers, and local Android prerequisites and reports actionable fixes.

If the app uses a non-default flavor, pass the same --app <key> that you use with hst run.

Run on an Android TV Emulator​

The sim target means an Android Virtual Device here. It is deliberately distinct from the browser preview:

npx hst run android-tv dev sim --device "Television_1080p"

Use --hot-reload only when you want the native host to load JavaScript from the development server:

npx hst run android-tv dev sim \
  --device "Television_1080p" \
  --hot-reload

Use --bundled to exercise the packaged JavaScript and assets that are closer to a release:

npx hst run android-tv dev sim \
  --device "Television_1080p" \
  --bundled

Do not use the emulator positional alias for an Android Virtual Device. In HST run planning, browser/web/emulator select the browser runtime; sim selects the vendor-native virtual device.

Run on a Physical Device​

Enable developer access and USB or network ADB for the target, then select the discovered serial or device name:

npx hst target:list android-tv --target device
npx hst run android-tv dev device --device "<serial-or-name>"

HST builds, installs, launches, and streams logs unless you pass --no-logs. Use --no-build only when the native output is already current.

What to Verify Natively​

The browser is useful for shared layout and state work, but it does not replace the Android TV runtime. Verify these on an AVD and on representative physical hardware:

  • DPAD focus entry, exits, long presses, key repeats, and Back behavior
  • process restart, suspend/resume, and activity recreation
  • native video, audio focus, casting, authentication, purchases, and notifications
  • network loss, slow responses, and app recovery
  • overscan-safe layout, text metrics, image memory, and sustained scrolling performance
  • bundled startup with production-like build config

Executable native-system service probes live under src/hosanna-ui-examples/rigs/native-system/ in hosanna-ui-samples-public.

Android Studio and Release Builds​

Open platforms/android in Android Studio when you need native dependency work, manifest/resource changes, profiling, signing, or Play release configuration. Keep vendor SDK code in the Android project and expose a small typed service to shared Hosanna code.

Before release, run a bundled production build through the project’s configured HST/Gradle path, then inspect and sign the resulting Android artifact with the app’s release configuration. Signing keys and vendor credentials belong in ignored local/CI secret stores, never tracked build config.

Talk to us