에러 대응

The latest service changes have not yet been reflected in this content. We will update the content as soon as possible. Please refer to the Korean version for information on the latest updates.

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 확인
변경 후 에뮬레이터 재시작

Documentation Index