본문으로 건너뛰기

에러 처리 (Error Handling)

Appify SDK는 통신 과정이나 네이티브 작업 중 발생하는 에러를 체계적으로 관리할 수 있도록 커스텀 에러 클래스를 제공합니다.

에러 클래스​

AppifyError​

모든 SDK 에러의 베이스 클래스입니다.

  • code: 에러 코드
  • message: 에러 메시지
  • details: 추가 상세 정보 (객체)

주요 에러 클래스 목록​

에러 클래스코드설명
TimeoutErrorTIMEOUT네이티브 응답이 지정된 시간 내에 오지 않을 때
BridgeNotAvailableErrorBRIDGE_NOT_AVAILABLE네이티브 브릿지가 없는 환경(일반 브라우저 등)에서 호출 시
NativeErrorNATIVE_ERROR네이티브 코드 실행 중 에러 발생 시
PermissionDeniedErrorPERMISSION_DENIED필요한 권한이 거부되었을 때
ConcurrentRequestErrorCONCURRENT_REQUEST동일한 요청이 이미 진행 중일 때
NotInitializedErrorNOT_INITIALIZEDSDK 초기화 전에 메서드 호출 시
SDKDestroyedErrorSDK_DESTROYEDSDK가 destroy된 후 메서드 호출 시

에러 처리 패턴​

try...catch 블록을 사용하여 안전하게 에러를 처리할 수 있습니다.

import { 
  appify, 
  TimeoutError, 
  BridgeNotAvailableError,
  NotInitializedError,
  SDKDestroyedError 
} from '@nolraunsoft/appify-sdk';

async function safeCall() {
  try {
    const data = await appify.storage.getItem('my_data');
  } catch (error) {
    if (error instanceof NotInitializedError) {
      console.error('SDK가 초기화되지 않았습니다. initialize()를 먼저 호출하세요.');
    } else if (error instanceof SDKDestroyedError) {
      console.error('SDK가 이미 destroy되었습니다.');
    } else if (error instanceof TimeoutError) {
      console.error('응답 시간이 초과되었습니다.');
    } else if (error instanceof BridgeNotAvailableError) {
      console.warn('앱 환경이 아닙니다. 폴백 처리를 시작합니다.');
    } else {
      console.error('알 수 없는 에러가 발생했습니다:', error.message);
    }
  }
}

초기화 관련 에러​

NotInitializedError​

SDK 메서드 호출 시 initialize()가 완료되지 않으면 발생합니다.

SDK는 내부적으로 100ms 동안 초기화 완료를 대기합니다:

  • 100ms 이내에 초기화 완료 → 요청 정상 진행
  • 100ms 초과 시 미완료 → NotInitializedError 발생
// 잘못된 사용 - 초기화 전 호출
const info = await appify.device.getInfo(); // NotInitializedError 발생 가능

// 올바른 사용
await appify.initialize();
const info = await appify.device.getInfo(); // 정상 동작

SDKDestroyedError​

destroy() 호출 후 SDK 메서드를 사용하면 발생합니다.

appify.destroy();
const info = await appify.device.getInfo(); // SDKDestroyedError 발생

에러 코드 참조​

코드의미대응 방법
TIMEOUT네이티브 응답 타임아웃네트워크 상태 확인, 재시도
BRIDGE_NOT_AVAILABLE웹뷰 환경 아님appify.isWebview 체크 후 분기 처리
NATIVE_ERROR네이티브 측 오류에러 상세 정보 확인
PERMISSION_DENIED권한 거부사용자에게 권한 필요성 안내
CONCURRENT_REQUEST중복 요청이전 요청 완료 후 재시도
NOT_INITIALIZED미초기화initialize() 호출 확인
SDK_DESTROYEDSDK 파괴됨새 인스턴스 필요 (페이지 새로고침)