React Native TV 모범 사례
개요
Apple TV, Android TV, Fire TV, Amazon Vega/Kepler, Tizen, webOS 등 TV 플랫폼을 대상으로 하는 React Native 기반 앱을 위한 TV 특화 검토 가이드입니다.
이 스킬은 TV 환경의 차이점(리모컨 입력, 포커스 엔진, 10피트 레이아웃, 플랫폼 패키징, 재생/DRM, 저메모리 TV 하드웨어, TV 접근성)에만 사용하세요. 일반적인 React Native 성능 또는 아키텍처 문제는 react-native-best-practices를 참조하세요.
스킬 형식
참조 파일은 주제 접두사별로 그룹화됩니다.
focus-*: 포커스 엔진, 포커스 가이드, 포커스 이벤트 성능nav-*: D-패드 내비게이션, 뒤로/메뉴 동작, 키보드/검색 입력design-*: 10피트 타이포그래피, 레이아웃, 색상, 포커스 가시성perf-*: TV 하드웨어에서의 시작, 메모리, 목록, 애니메이션 및 네트워크 제약video-*: 재생 아키텍처, DRM/프로토콜 선택, 디버깅a11y-*: TV 접근성 구현 및 감사 점검setup-*: 스택 감지, 설정, 아키텍처, 크로스 플랫폼 동작test-*및release-*: 테스트 범위, E2E 및 CI/릴리스 워크플로우
적용 시점
앱이 TV 플랫폼을 대상으로 하고 다음 작업과 관련된 경우 이 스킬을 적용하세요.
- 포커스 이동, 포커스 가시성, 포커스 복원 또는 리모컨/D-패드 입력
- TV 레이아웃 가독성, 오버스캔/안전 영역 또는 10피트 UI 밀도
- TV 플레이어 컨트롤, 매니페스트, DRM, 디코더 지원 또는 재생 오류
- 저메모리 TV 하드웨어에서의 성능(특히 비디오 또는 대형 캐러셀)
- 화면 판독기, 자막, 포커스 순서 또는 리모컨 전용 상호 작용을 통한 TV 접근성
react-native-tvos, Expo TV, Amazon Vega/Kepler, Tizen 또는 webOS 플랫폼 설정
시작하기 전에 — TV 스택 식별
이 스킬은 여러 TV 스택을 다룹니다. 설정 문제를 지적하기 전에 앱이 대상으로 하는 스택을 감지하세요. Vega/Kepler 또는 웹 기반 TV 앱에 react-native-tvos, tvOS Podfile 또는 Android TV 매니페스트를 요구하면 오탐지가 발생합니다.
| 스택 | 감지 방법 | 설정 기대 사항 |
|---|---|---|
| react-native-tvos (Apple TV, Android TV, Fire TV) | package.json에 "react-native": "npm:react-native-tvos@…" | tvOS Podfile (platform :tvos); Android TV leanback/LEANBACK_LAUNCHER 매니페스트 항목; TV 에뮬레이터/시뮬레이터 |
| Expo + react-native-tvos | 위 조건 및 app.json에 @react-native-tvos/config-tv | EXPO_TV=1 prebuild; react-native-tvos 버전은 Expo SDK와 일치해야 함; 모든 Expo 기능/라이브러리가 TV에서 사용 가능한 것은 아님 |
| Amazon Vega / Kepler | Vega/Kepler SDK 및 도구 (@amazon-devices/* 의존성, Kepler 매니페스트); react-native-tvos 없음 | Amazon의 Vega/Kepler 툴체인 — react-native-tvos, tvOS Podfile 및 Android TV 매니페스트는 적용되지 않음 |
| 웹 기반 TV (Tizen, webOS) | 웹 번들러 (Rsbuild/webpack) + 플랫폼 패키징; spatial-nav 라이브러리 | 플랫폼 SDK 패키징; 포커스를 위한 @noriginmedia/norigin-spatial-navigation |
포커스, 10피트 디자인, 성능, 접근성, 플레이어 가이드는 이 모든 스택에 적용됩니다. 설정/빌드 기대 사항만 스택별로 다릅니다.
검토 규칙
- 설정 조언 전에 대상 스택을 확인하세요.
- 명령형 포커스 호출 또는 광범위한
nextFocus*맵보다 자연스러운 포커스 순서와 포커스 가이드를 선호하세요. - 포커스 손실, 보이지 않는 포커스, 깨진 뒤로/메뉴 동작을 탐색 버그로 처리하세요.
- 시각적 세부 사항을 조정하기 전에 TV 시청 거리에서 가독성, 안전 영역 및 포커스 상태를 확인하세요.
- 성능 수정이 완료되었다고 보고하기 전에 지원되는 가장 약한 TV 장치에서 프로파일링하세요.
- 재생 실패를 레이어별로 분리하세요: 매니페스트 요청, DRM 라이선스 교환, 디코더 기능, 플레이어 상태, React UI 컨트롤.
우선순위 기반 지침
| 우선순위 | 카테고리 | 영향 | 접두사 |
|---|---|---|---|
| 1 | 포커스 및 D-패드 내비게이션 | 치명적 | focus-*, nav-* |
| 2 | 목록, 애니메이션 및 입력 성능 | 치명적 | perf-* |
| 3 | 재생 및 DRM 실패 | 높음 | video-* |
| 4 | 10피트 가독성 및 레이아웃 | 높음 | design-* |
| 5 | TV 접근성 | 높음 | a11y-* |
| 6 | 스택 설정, 테스트 및 릴리스 | 중간 | setup-*, test-*, release-* |
빠른 참조
- 패키지 파일, 매니페스트, 네이티브 폴더 및 플랫폼 도구에서 TV 스택을 감지합니다.
- 마우스/터치 가정이 아닌 리모컨 또는 D-패드 경로로 탐색을 재현합니다.
- 포커스된 요소가 항상 보이고, 도달 가능하며, 모달/라우트 후에 복원되는지 확인합니다.
- React 컨트롤을 변경하기 전에 네트워크/DRM 레이어부터 재생 실패를 확인합니다.
- 지원되는 가장 약한 TV 대상에서 목록, 애니메이션, 메모리 및 시작 작업을 측정합니다.
참조
포커스 및 내비게이션
| 파일 | 영향 | 설명 |
|---|---|---|
| focus-management.md | 치명적 | 포커스 엔진, 포커스 가이드, nextFocus*, 포커스 복원 |
| focus-performance.md | 치명적 | 포커스 이벤트 처리로 인한 프레임 드롭 방지 |
| nav-directional.md | 치명적 | TV 플랫폼 간 방향 탐색 규칙 |
| nav-patterns.md | 치명적 | 전역/지역 탐색, 모달, 탭 및 뒤로 동작 |
| nav-keyboard.md | 중간 | 리모컨을 사용한 검색 및 텍스트 입력 |
디자인
| 파일 | 영향 | 설명 |
|---|---|---|
| design-10foot.md | 높음 | 10피트 검토 휴리스틱 |
| design-typography.md | 높음 | TV 글꼴 크기 및 가독성 |
| design-layout.md | 높음 | 안전 영역, 간격, 캐러셀 및 포커스 공간 |
| design-color.md | 중간 | 대비 및 TV 디스플레이 색상 제약 |
성능
| 파일 | 영향 | 설명 |
|---|---|---|
| perf-overview.md | 높음 | TV 성능 목표 및 프로파일링 순서 |
| perf-lists.md | 치명적 | 가상화된 행 및 포스터가 많은 목록 |
| perf-animations.md | 치명적 | 포커스 및 전환 애니메이션 성능 |
| perf-memory.md | 높음 | 저메모리 TV 충돌 및 이미지/비디오 압박 |
| perf-network.md | 높음 | 원격 입력, 요청 지연 및 네트워크 복원력 |
비디오, 접근성, 설정, 테스트
| 파일 | 영향 | 설명 |
|---|---|---|
| video-streaming.md | 높음 | TV 플랫폼 프로토콜/DRM 선택 |
| video-players.md | 높음 | 플레이어 선택 및 사용자 정의 컨트롤 |
| video-debugging.md | 높음 | 매니페스트, DRM, 코덱 및 재생 디버깅 |
| a11y-overview.md | 중간 | TV 특화 접근성 차이점 |
| a11y-implementation.md | 높음 | 접근 가능한 레이블, 역할, 라이브 리전 및 포커스 |
| a11y-checklist.md | 중간 | 출시 접근성 감사 체크리스트 |
| setup-getting-started.md | 중간 | react-native-tvos 및 Expo TV 설정 |
| setup-cross-platform.md | 중간 | 플랫폼 감지 및 크로스 플랫폼 주의 사항 |
| setup-architecture.md | 중간 | 코드 공유 및 프로젝트 구조 |
| test-strategy.md | 중간 | TV 테스트 범위 및 범위 분할 |
| test-javascript.md | 중간 | JS 수준의 리모컨/포커스 테스트 도우미 |
| test-e2e.md | 중간 | Appium 및 TV E2E 범위 |
| release-cicd.md | 중간 | CI, 빌드 지문 및 릴리스 점검 |
문제 → 스킬 매핑
| 증상 | 시작 위치 |
|---|---|
| "포커스가 잘못된 요소로 이동합니다" | focus-management.md → 디버깅 섹션 |
| "목록 스크롤 시 앱이 멈춥니다" | perf-lists.md → 가상화 |
| "Fire TV에서 애니메이션이 끊깁니다" | perf-animations.md → 네이티브 드라이버 |
| "TV에서 텍스트가 너무 작습니다" | design-typography.md → 최소 크기 |
| "비디오가 재생되지 않음 / DRM 오류" | video-streaming.md → DRM 섹션 |
| "화면 판독기가 요소를 건너뜁니다" | a11y-implementation.md → 역할 및 레이블 |
| "뒤로 버튼이 제대로 작동하지 않습니다" | nav-patterns.md → 뒤로 탐색 |
| "키보드가 콘텐츠를 가립니다" | nav-keyboard.md → 내장 vs 사용자 정의 |
| "앱 시작에 시간이 오래 걸립니다" | perf-overview.md → 시작 시간 |
| "이미지로 인해 메모리 충돌이 발생합니다" | perf-memory.md → 이미지 최적화 |
| "CI 파이프라인에 몇 시간이 걸립니다" | release-cicd.md → 지문 |
| "플랫폼 간에 코드를 공유하는 방법" | setup-architecture.md → 코드 공유 |
보안 (TV 특화)
일반적인 의존성/입력 위생은 다른 RN 앱과 동일하게 적용됩니다. TV 특화 차이점은 다음과 같습니다.
- FairPlay/Widevine/PlayReady 키를 클라이언트 코드에 절대 포함하지 마십시오. 라이선스 서버를 신뢰 경계로 간주하고 DRM 토큰을 서버에서 발급하도록 유지하세요.