에러 처리

개요

DARO SDK는 광고 로드가 실패하면 통합 에러 객체 DaroError를 전달합니다. 모든 오류는 동일한 DaroErrorCode 체계로 변환되므로, 퍼블리셔는 하나의 분기 로직으로 에러를 처리할 수 있습니다.

DaroError 객체

로드 실패 콜백은 DaroError 객체를 전달합니다. 주요 프로퍼티는 다음과 같습니다.

프로퍼티	타입	설명
`errorCode`	`Int`	통합 에러 코드의 정수 값입니다.
`errorCodeName`	`DaroErrorCode`	통합 에러 코드의 이름(enum)입니다. 분기 처리에 사용하세요.
`errorMessage`	`String`	오류 메시지입니다. 로깅·디버깅에 활용하세요.
`latency`	`Int`	광고 요청에 소요된 시간(ms)입니다.

통합 에러 코드

DaroErrorCode는 아래 코드로 구성됩니다. 분기 처리는 정수 값이 아닌 errorCodeName(enum)으로 하는 것을 권장합니다.

초기화·설정 오류

코드	이름	발생 조건	권장 대응
`-1`	`UNSPECIFIED`	분류되지 않은 일반 오류입니다.	`errorMessage`를 확인하고 잠시 후 다시 요청하세요.
`-2`	`NOT_INITIALIZED`	SDK가 초기화되지 않은 상태에서 광고를 요청했습니다.	SDK 초기화가 완료된 뒤 광고를 요청하세요.
`-3`	`INITIALIZATION_FAILED`	SDK 초기화가 최종적으로 실패했습니다.	네트워크 상태를 확인하고 잠시 후 초기화를 재시도하세요.

광고 로드 실패

코드	이름	발생 조건	권장 대응
`204`	`NO_FILL`	광고 요청은 성공했으나 노출 가능한 광고가 없습니다.	광고가 없을 때 발생하는 정상적인 응답입니다. 잠시 후 다시 요청하세요. 지속되면 app-ads.txt 설정을 확인하세요.
`-5001`	`AD_LOAD_FAILED`	요청한 광고를 로드하지 못했습니다.	일시적 실패일 수 있습니다. 잠시 후 다시 요청하세요.
`-5603`	`INVALID_AD_UNIT_IDENTIFIER`	잘못되었거나 비활성화된 Ad Unit Key, 앱 패키지명 불일치, 애드유닛 생성 직후 등입니다.	Ad Unit Key와 앱 패키지명 설정을 점검하세요. 애드유닛을 방금 생성했다면 반영에 30~60분이 걸립니다.

네트워크 오류

코드	이름	발생 조건	권장 대응
`-1009`	`NO_NETWORK`	기기가 인터넷에 연결되어 있지 않습니다.	기기의 인터넷 연결 상태를 확인하세요.
`-1000`	`NETWORK_ERROR`	일반적인 네트워크·서버 통신 오류입니다.	잠시 후 다시 요청하세요.
`-1001`	`NETWORK_TIMEOUT`	광고 요청이 제한 시간 안에 완료되지 않았습니다.	잠시 후 다시 요청하세요.

전체 화면 광고 상태 오류

전체 화면 광고(인터스티셜 광고·리워드 비디오 광고 등)의 로드/표시 순서가 맞지 않을 때 발생하는 오류입니다. 광고가 로드된 뒤 표시를 요청했는지 확인하세요.

코드	이름	발생 조건	권장 대응
`-23`	`FULLSCREEN_AD_ALREADY_SHOWING`	이미 전체 화면 광고가 표시 중인데 다른 전체 화면 광고를 표시하려 했습니다.	별도 처리가 필요 없습니다.
`-24`	`FULLSCREEN_AD_NOT_READY`	광고 로드가 완료되기 전에 표시를 시도했습니다.	광고 로드 완료 후 표시하세요.
`-25`	`FULLSCREEN_AD_INVALID_VIEW_CONTROLLER`	유효하지 않은 화면에서 전체 화면 광고를 표시하려 했습니다.	유효한 화면(Activity)에서 광고를 표시하세요.
`-26`	`FULLSCREEN_AD_ALREADY_LOADING`	이미 로딩 중인 전체 화면 광고를 다시 로드하려 했습니다.	중복 로드 호출을 피하세요.
`-27`	`FULLSCREEN_AD_LOAD_WHILE_SHOWING`	광고가 표시 중인데 동일한 광고를 다시 로드하려 했습니다.	광고 표시가 끝난 후 다시 로드하세요.

에러 처리 예시

로드 실패는 광고 포맷별 리스너의 onAdLoadFail(error: DaroError) 콜백으로 전달됩니다. errorCodeName으로 분기하세요.

loader.setListener(object : DaroInterstitialAdLoaderListener {
    override fun onAdLoadSuccess(ad: DaroInterstitialAd, adInfo: DaroAdInfo) {
    }

    override fun onAdLoadFail(error: DaroError) {
        when (error.errorCodeName) {
            DaroErrorCode.NO_FILL,
            DaroErrorCode.AD_LOAD_FAILED -> retryLater()
            DaroErrorCode.NO_NETWORK,
            DaroErrorCode.NETWORK_ERROR,
            DaroErrorCode.NETWORK_TIMEOUT -> showNetworkGuide()
            DaroErrorCode.INVALID_AD_UNIT_IDENTIFIER -> reportConfigError(error.errorMessage)
            else -> retryLater()
        }
    }
})

기존 onAdLoadFail(err: DaroAdLoadError) 콜백은 하위 호환을 위해 그대로 유지되지만 deprecated 되었습니다. 기존 콜백과 새 콜백이 모두 호출되므로, 새 코드는 onAdLoadFail(error: DaroError)만 구현하는 것을 권장합니다.

DARO 2.0 SDK 마이그레이션

다로 시작하기

SDK 통합하기

DARO 사용하기

FAQ

레거시 SDK

개요

DaroError 객체

통합 에러 코드

초기화·설정 오류

광고 로드 실패

네트워크 오류

전체 화면 광고 상태 오류

에러 처리 예시

​개요

​DaroError 객체

​통합 에러 코드

​초기화·설정 오류

​광고 로드 실패

​네트워크 오류

​전체 화면 광고 상태 오류

​에러 처리 예시

개요

DaroError 객체

통합 에러 코드

초기화·설정 오류

광고 로드 실패

네트워크 오류

전체 화면 광고 상태 오류

에러 처리 예시