고급 기능

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

1. 네트워크 에러 대응

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

1.1 네트워크 에러 콜백

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

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

1.2 네트워크 관련 설정

data-nf-retry-count: 요청 실패 시 자동 재시도 횟수. 기본 0 · 최소 0 · 최대 10. 재시도 후에도 실패하면 NetworkError 반환.
data-nf-network-timeout: 네트워크 응답을 기다리는 최대 시간(ms). 기본 3,000 · 최소 100 · 최대 10,000. 초과 시 retry-count만큼 재시도.
data-nf-health-check-url: 네트워크 에러 시 지정 URL로 Health Check를 수행해 단순 지연(1002)인지 서버 장애(1001)인지 구분.

1.3 우회·복구 설정

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

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

넷퍼넬 기본 대기실을 사용하지 않고 자체 커스텀 대기실을 적용합니다. data-nf-use-netfunnel-template=false로 설정하면 대기실이 뜨지 않고, 콜백에서 Continue 상태값과 대기 정보를 반환합니다.

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

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

3. 브라우저 스토리지

진입 키를 브라우저에 저장할 때 저장소 타입을 설정합니다. 기본적으로 cookie와 session storage를 모두 사용하지만, 상황에 따라 하나만 사용하도록 제한할 수 있습니다. (data-nf-storage-type)

저장소 타입	특징	데이터 유지 기간	사용 사례
`cookie`	서버와 공유	1일	브라우저를 종료해도 진입 키를 유지해야 하는 경우
`session`	탭 별로 저장	탭 종료 시까지	탭 별 독립 세션 관리가 필요한 경우
`both`	기본값	-	일반적인 경우 (권장)

쿠키 도메인 설정

진입 키를 쿠키에 저장할 때 현재 페이지 도메인 기준으로 저장됩니다. 진입 요청(nfStart)과 반납(nfStop) 페이지의 서브도메인이 다르면 쿠키를 공유하도록 data-nf-custom-cookie-domain을 설정해야 합니다.

4. 개발자 도구 탐지

사용자가 개발자 도구로 웹 애플리케이션을 분석·조작하는 것을 방지하기 위해, 개발자 도구가 열렸을 때를 감지하여 특정 동작을 수행할 수 있습니다.

Netfunnel.devtoolsAddListener(callback): 개발자 도구의 열림/닫힘 상태를 감지하는 리스너를 등록합니다. 콜백은 isOpen(Boolean)을 받습니다.
Netfunnel.devtoolsLaunch(): 탐지 기능을 시작합니다.

Netfunnel.devtoolsAddListener(function (isOpen) {
  if (isOpen) {
    // 개발자 도구가 열렸을 때: 경고 노출 또는 특정 페이지로 이동
    alert('개발자 도구 사용이 감지되었습니다.');
  }
});

Netfunnel.devtoolsLaunch();

5. 진입 키 자동 반납 처리

URL 트리거 적용 시 진입 후 넷퍼넬 키를 자동으로 반납해 다음 대기자가 진입하도록 처리합니다. 즉시 반납하지 않고 세그먼트에 설정한 타임아웃 시점에 반납하려면 data-nf-return-key를 사용합니다.

설정값	동작 방식	사용 시기
`true` (기본값)	진입 후 즉시 키 반납	일반적인 경우
`false`	타임아웃까지 키 보유	세그먼트 타임아웃 설정으로 키 반납 시간을 일괄 제어하고 싶은 경우

6. Frameset 지원

Frameset 구조로 제작된 페이지에 코드 기반으로 적용하는 방법입니다. frameset 태그가 있는 HTML에 초기화 코드를 삽입한 뒤, 시작 함수의 파라미터에 frame 설정값을 추가합니다.

key	type	설명	예시
`frameName`	string	넷퍼넬 대기실을 띄울 frame의 name 속성	“content”
`useFrameBlock`	boolean	지정한 frame 외 나머지 frame을 block 처리	true

// frame name이 navibar인 프레임의 버튼 클릭 시,
// frame name이 content인 프레임에 대기실을 노출
nfStart({
  projectKey: '{PROJECT_KEY}',
  segmentKey: '{SEGMENT_KEY}',
  frameName: 'content',
  useFrameBlock: true
}, function (response) {
  nfCallback(response);
});