고급 기능

NetFUNNEL Android 에이전트의 기본 기능을 넘어서는 고급 활용법을 안내합니다. 아래 기능을 사용하기 전에 기본 연동(통합 가이드)을 완료하고 개발 환경에서 충분히 테스트하세요.

1. 네트워크 에러 대응

사용 중 발생할 수 있는 네트워크 에러를 식별하고, 상황에 맞는 처리·우회·복구 방법을 설정합니다.

1.1 네트워크 에러 콜백

네트워크 문제 발생 시 시작 콜백의 onNetworkError가 호출됩니다.

콜백	statusCode	message	설명
onNetworkError	1001	Network Not Connected	네트워크 연결 차단 (Wi-Fi·셀룰러 차단)
onNetworkError	1002	Network Timeout	네트워크 응답 지연으로 인한 시간 초과 · 서버 장애

1.2 네트워크 관련 설정

retryCount: 요청 실패 시 자동 재시도 횟수. 기본 0 · 최소 0 · 최대 10. 재시도 후에도 실패하면 onNetworkError 호출.
networkTimeout: 네트워크 응답을 기다리는 최대 시간(ms). 기본 3,000 · 최소 100 · 최대 10,000. 초과 시 retryCount만큼 재시도.
healthCheckUrl: 네트워크 에러 시 지정 URL로 Health Check를 수행해 단순 지연(1002)인지 서버 장애(1001)인지 구분.

Netfunnel.initialize(
    clientId = "{CLIENT_ID}",
    networkTimeout = 3000,
    retryCount = 3,
    healthCheckUrl = "{HEALTH_CHECK_URL}"
)

1.3 우회·복구 설정

errorBypass: 기본 false. true로 설정하면 onError·onNetworkError 대신 onSuccess(300)를 호출해 서비스 진입을 허용합니다. 이 경우 필수 구현 콜백은 onSuccess 하나입니다. (테스트 환경, 네트워크 여부가 핵심 흐름에 영향을 주지 않는 경우)
useNetworkRecoveryMode: 기본 false. 대기 중 네트워크가 끊겨도 대기실을 유지하며 재연결을 시도합니다.

2. 넷퍼넬 대기실 미사용 (커스텀 대기실)

넷퍼넬 기본 대기실(WebView)을 사용하지 않고 앱 화면으로 직접 만든 커스텀 대기실을 적용합니다. 초기화 시 useNetfunnelTemplate = false로 설정하면 대기실이 뜨지 않고, 대기 중에는 시작 콜백의 onContinue(201)가 대기 정보와 함께 호출됩니다.

parameter	type	설명	예시
`statusCode`	Int	대기 상태 코드	201
`message`	String	대기 상태 메시지	Waiting Continue
`aheadWait`	Int	내 앞 대기자 수	0
`behindWait`	Int	내 뒤 대기자 수	0
`waitTime`	String	예상 대기 시간	00:00:00
`progressRate`	Int	진행률(%)	0

override fun onContinue(
    statusCode: Int, message: String,
    aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int
) {
    // 커스텀 대기실 UI 갱신
    binding.tvAhead.text = "내 앞 대기자: $aheadWait 명"
    binding.tvWaitTime.text = "예상 대기 시간: $waitTime"
    binding.progressBar.progress = progressRate
}

커스텀 대기실에서는 aheadWait, behindWait, waitTime, progressRate 값을 활용해 대기 UI를 직접 구성합니다.

3. 대기실 투명화

넷퍼넬 대기실(WebView)의 배경을 투명하게 처리해, 앱의 기존 화면 위에 대기실이 겹쳐 보이도록 합니다. (isTransparent)

설정값	동작 방식
`true`	대기실 배경이 투명해져 앱의 기존 화면이 배경으로 보입니다.
`false` / 미설정 (기본값)	대기실 배경을 불투명하게 표시합니다.

Netfunnel.initialize(
    clientId = "{CLIENT_ID}",
    isTransparent = true
)

4. 진입 키 무효화

에이전트가 앱에 저장한 진입 키를 제거해, 해당 사용자가 다시 대기하도록 합니다. (nfClear)

대기가 발생하면 에이전트는 진입 키를 앱 데이터(SharedPreferences)에 저장합니다. 진입 패스를 사용하면 저장된 키를 재사용해 대기 없이 재진입할 수 있는데, 특정 시점(예: 로그아웃, 이벤트 참여 완료)에 키를 무효화하면 다시 대기열을 거치게 할 수 있습니다.

파라미터	타입	설명
`activity`	Activity	현재 화면
`projectKey`	String?	삭제할 프로젝트 키
`segmentKey`	String?	삭제할 세그먼트 키

전달하는 키 조합에 따라 삭제 범위가 달라집니다.

projectKey	segmentKey	삭제 범위
전달	전달	해당 프로젝트의 특정 세그먼트 진입 키만 제거
전달	`null`	해당 프로젝트의 모든 세그먼트 진입 키 제거
`null`	`null`	모든 프로젝트·세그먼트의 진입 키 제거

// 특정 세그먼트의 진입 키만 제거
Netfunnel.nfClear(this, "{PROJECT_KEY}", "{SEGMENT_KEY}")

// 프로젝트의 모든 세그먼트 진입 키 제거
Netfunnel.nfClear(this, "{PROJECT_KEY}", null)

// 모든 진입 키 제거
Netfunnel.nfClear(this, null, null)

5. 사용자 ID 식별

반복 요청 차단을 사용자 ID 기준으로 적용하려면, 초기화 시 userId에 로그인한 사용자의 ID를 전달합니다. 차단 유형이 ID 또는 All인 경우 이 값으로 사용자를 식별하며, 콘솔의 영구 차단·우회(화이트리스트) 목록도 이 ID를 기준으로 동작합니다.

Netfunnel.initialize(
    clientId = "{CLIENT_ID}",
    userId = "{USER_ID}"
)

콜백	statusCode	설명
onSuccess	303	우회(화이트리스트) 목록에 등록된 ID·IP 요청
onBlock	302	영구 차단(블랙리스트) 목록 · 반복 요청 차단에 걸린 ID·IP 요청