firetv-leanback

Files (1)

• SKILL.md

SKILL.md (first lines)

# Fire TV / Android TV (leanback)

> Android TV and Fire TV (Fire OS) share the same Android runtime and require the same manifest configuration to be recognized as TV apps by the system. Without these settings, an APK installs but doesn't appear in the TV launcher, or worse: appears with the wrong icon and gets rejected from the store.

This skill covers what `apps/expo-multi-tv/app.json` and the generated `AndroidManifest.xml` must contain.

## The four non-negotiables

For Fire OS / Android TV to recognize the app as a TV app:

1. **`isTV: true`** in the Expo config-tv plugin options.
2. **`androidTVBanner`** asset (exactly 400×240 PNG) referenced from `app.json`.
3. **`LEANBACK_LAUNCHER` intent filter** on the main activity. The plugin generates this when `isTV: true`.
4. **`uses-feature android.software.leanback` (required=false)** in the manifest. Plugin handles it.

If the agent finds itself manually editing `AndroidManifest.xml`, **stop.** The plugin should produce it. Manual edits get wiped on next prebuild.

## `app.json` shape (verified against template)

```json
{
  "expo": {
    "name": "AppName",
    "slug": "app-slug",
    "plugins": [
      [
        "@react-native-tvos/config-tv",
        {
          "isTV": true,
          "androidTVBanner": "./assets/icon-400x240.png"
        }
      ]
    ],
    "android": {
      "package": "com.example.appname",
      "versionCode": 1
    },
    "ios": {
      "bundleIdentifier": "com.example.appname"
    }
  }
}
```

Notes:
- Plugin order matters. `@react-native-tvos/config-tv` should come before any plugin that modifies the Android manifest.
- The Android `package` and iOS `bundleIdentifier` should match your domain. Fire TV store and Apple TV App Store check these.

## Banner specs (the most common bug)

- **Exact dimensions: 400 × 240 pixels.** Not 800×480. Not 200×120. Exact.
- PNG, RGB, no alpha needed (but supported).
- Visually balanced — there is no safe zone padding in the launcher.
- Includes app name as text (the launcher doesn't render the app name beside the banner).

The `replace_assets` tool generates this if not provided. Generation rule:
- Background = `brand.background_color` or `brand.primary_color` (whichever has better contrast with the logo).
- Logo or wordmark centered, fitting within a 360×200 inner area.
- Output to `apps/expo-multi-tv/assets/icon-400x240.png`.

## Fire TV specifics on top of Android TV

Fire TV is Android TV with extra:

- **Amazon Appstore submission** rather than Google Play. Different store entry, different review.
- **No Google Play Services.** If a dep needs Play Services (e.g. some auth libs), it won't work on Fire TV. Audit deps.
- **Different system back behavior.** Long-press Home opens the Amazon overlay. Generally not the app's concern.
- **D-pad center is "select" same as Android TV.** Voice search via remote follows the same intent system.

## Distinguishing Fire OS from Android TV in code (rare)

You usually don't need to. The build artifact is the same APK and runtime APIs are identical. Reach for runtime detection only for:

- Deep-linking that uses Amazon-specific URI schemes.
- Analytics tagging by manufacturer.
- Account integration (Amazon account vs Google account).

If you need it:
```ts
import { NativeModules, Platform } from "react-native";
const isFireOS = Platform.OS === "android" &&
  /amazon/i.test(NativeModules.PlatformConstants?.Manufacturer ?? "");
```

This goes in a single utility file (`isFireOS.android.ts`) — don't sprinkle it.

## D-pad center button = select (the gotcha)

Android TV remote sends `KEYCODE_DPAD_CENTER` for the center press. React TV Space Navigation translates this to a "select" event on the focused element. **It does not translate to `onPress` on a regular `<Pressable>` unless the Pressable is wrapped in a focusable.**

Use the template's themed `<Pressable>` (which is already wrapped) or wrap manually with `<SpatialNavigationFocusableView>`. Don't use `<TouchableOpacity>` — it responds to touch, not to focus + select.

## Prebuild → APK flow

```bash
# In apps/expo-multi-tv/
EXPO_TV=1 npx expo prebuild --platform android --clean
cd android && ./gradlew assembleDebug
cd ..
android describe --project_dir=android
android run \
  --apks=android/app/build/outputs/apk/debug/app-debug.apk \
  --device=<deviceId> \
  --activity=.MainActivity
```

`--device` is required when multiple emulators or devices are connected,
including a phone emulator that may also be running. Forget this and the app
can install on the wrong target.

To find Fire TV device IDs:
```bash
adb devices
# AFTSS, AFTMM, AFTT, etc. are Fire TV model codes
```

To find the leanback emulator:
```bash
android emulator list

From giolaq/tv-build-harness, MIT-0.

More from giolaq/tv-build-harness