고급 기능

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

1. 네트워크 에러 대응

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

1.1 네트워크 에러 콜백

네트워크 문제 발생 시 콜백 함수에서 NetworkError 상태값을 반환합니다.

status	statusCode	message	설명
NetworkError	1001	Network Not Connected	네트워크 연결 차단
NetworkError	1002	Network Timeout	네트워크 응답 지연으로 인한 시간 초과 · 서버 장애

1.2 네트워크 관련 설정

retryCount: 요청 실패 시 자동 재시도 횟수. 기본 0 · 최소 0 · 최대 10. 재시도 후에도 실패하면 NetworkError 반환.
networkTimeout: 네트워크 응답을 기다리는 최대 시간(ms). 기본 3,000 · 최소 100 · 최대 10,000. 초과 시 retryCount만큼 재시도.

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

1.3 우회·복구 설정

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

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

넷퍼넬 기본 대기실을 사용하지 않고 앱 화면으로 직접 만든 커스텀 대기실을 적용합니다. 초기화 시 useNetfunnelTemplate: false로 설정하면 대기실이 뜨지 않고, 대기 중에는 콜백에서 Continue 상태값과 대기 정보를 반환합니다.

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

const [waitInfo, setWaitInfo] = useState(null);

Netfunnel.nfStart('{PROJECT_KEY}', '{SEGMENT_KEY}', function (response) {
  if (response.status === 'Continue') {
    // 커스텀 대기실 UI 갱신
    const { aheadWait, waitTime, progressRate } = response;
    setWaitInfo({ aheadWait, waitTime, progressRate });
    return;
  }
  setWaitInfo(null);
  nfCallback(response);
});

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

3. 진입 키 반납 처리

진입한 사용자의 키가 반납되어야 다음 대기자가 진입할 수 있습니다. 종료 함수 호출 여부에 따른 동작은 다음과 같습니다.

제어 유형	종료 함수를 호출한 경우	종료 함수를 호출하지 않은 경우
기본 제어 (`nfStop`)	즉시 키 반납	세그먼트의 타임아웃 설정에 따라 자동 반납
구간 제어 (`nfStopSection`)	즉시 키 반납	사용자가 계속 구간 안에 있는 것으로 집계되어 다음 대기자의 진입이 늦어짐

useEffect(() => {
  // 화면을 벗어날 때 진입 키 반납
  return () => {
    Netfunnel.nfStopSection('{PROJECT_KEY}', '{SEGMENT_KEY}');
  };
}, []);

4. 사용자 ID 식별

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

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

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