고급 기능

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

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만큼 재시도.

await Netfunnel.instance.initialize(
  clientId: '{CLIENT_ID}',
  networkTimeout: 3000,
  retryCount: 3,
);

1.3 우회·복구 설정

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

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

넷퍼넬 기본 대기실을 사용하지 않고 앱 화면으로 직접 만든 커스텀 대기실을 적용합니다. 초기화 시 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

class WaitingCallback extends NetfunnelCallback {
  WaitingCallback(this.onWaitInfo);
  final void Function(int aheadWait, String waitTime, int progressRate) onWaitInfo;

  @override
  void onContinue(int statusCode, String message, int aheadWait,
      int behindWait, String waitTime, int progressRate) {
    // 커스텀 대기실 UI 갱신 (예: setState로 대기 정보 반영)
    onWaitInfo(aheadWait, waitTime, progressRate);
  }

  @override
  void onSuccess(int statusCode, String message) { /* 서비스 진입 */ }

  @override
  void onError(int statusCode, String message) { /* 서비스 진입 */ }

  @override
  void onNetworkError(int statusCode, String message) { /* 안내 또는 재시도 */ }
}

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

3. 서비스 환경 프로필

에이전트가 접속할 NetFUNNEL 서비스 환경을 지정합니다. (profile)

설정값	설명
`prod_tokyo` (기본값)	도쿄 리전 서비스 환경
`prod_us_east`	미국 동부 리전 서비스 환경

await Netfunnel.instance.initialize(
  clientId: '{CLIENT_ID}',
  profile: 'prod_us_east',
);

4. 사용자 ID 식별

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

await Netfunnel.instance.initialize(
  clientId: '{CLIENT_ID}',
  userId: '{USER_ID}',
);

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