에러 대응

Classic/VPC 환경에서 이용 가능합니다.

TV SDK에서 커스텀 에러 UI를 구성하는 방법을 안내합니다.

errorOverride

기본 에러 UI 대신 커스텀 에러 UI를 렌더링할 수 있습니다. errorOverride prop에 렌더 함수, React 컴포넌트, 또는 ReactNode를 전달합니다.

PlayerErrorInfo

커스텀 에러 UI에 전달되는 에러 정보 객체의 타입은 다음과 같습니다.

type PlayerErrorInfo = {
    errorCode: string | null;
    errorMessage: string | null;
    errorTitle: string | null;
};

방법 1: 렌더 함수

errorOverride에 렌더 함수를 전달하면 에러 정보를 받아 UI를 직접 구성할 수 있습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    errorOverride={(info) => (
        <View style={{
            flex: 1,
            justifyContent: 'center',
            alignItems: 'center',
            backgroundColor: '#000',
        }}>
            <Text style={{ color: '#fff', fontSize: 18 }}>
                에러: {info.errorCode}
            </Text>
            <Text style={{ color: '#aaa', fontSize: 14, marginTop: 8 }}>
                {info.errorMessage}
            </Text>
        </View>
    )}
    onBack={() => navigation.goBack()}
/>

방법 2: React 컴포넌트

errorOverride에 React 컴포넌트를 전달할 수 있습니다. 컴포넌트 PlayerErrorInfo를 props로 받습니다.

function MyErrorComponent({ errorCode, errorMessage }: PlayerErrorInfo) {
    return (
        <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
            <Text style={{ color: '#fff' }}>에러: {errorCode}</Text>
            <Text style={{ color: '#aaa' }}>{errorMessage}</Text>
        </View>
    );
}

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    errorOverride={MyErrorComponent}
    onBack={() => navigation.goBack()}
/>

방법 3: ReactNode

errorOverride에 정적인 ReactNode를 직접 전달할 수 있습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    errorOverride={
        <Text style={{ color: '#fff' }}>재생할 수 없는 영상입니다</Text>
    }
    onBack={() => navigation.goBack()}
/>

이벤트로 에러 감지

onEvent의 error 이벤트로도 에러를 감지할 수 있습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    onEvent={(event) => {
        if (event.type === 'error') {
            console.log('에러 발생:', event.data);
        }
    }}
    onBack={() => navigation.goBack()}
/>

자주 발생하는 문제

Q. 재생이 안 됩니다.

• accessKey가 유효한지 확인
• playlist에 file이 포함되어 있는지 확인
• 스트림 URL이 접근 가능한지 확인

Q. DRM 재생이 실패합니다.

• DRM은 시뮬레이터/에뮬레이터에서 동작하지 않으므로 실제 기기 테스트 필수
• Android TV는 Widevine, tvOS는 FairPlay 확인

Q. IMA 광고가 나오지 않습니다.

• 네이티브 빌드 플래그 확인(tvOS: $RNVideoUseGoogleIMA = true, Android: RNVideo_useExoplayerIMA=true)
• 플래그 변경 후 앱 리빌드 필수

Q. Android TV에서 D-pad가 동작하지 않습니다.

• 에뮬레이터 config.ini에서 hw.keyboard = yes 확인
• 변경 후 에뮬레이터 재시작