통합 가이드

1. 에이전트 소개

NetFUNNEL Browser 에이전트는 웹 브라우저에서 NetFUNNEL 서버와 통신하는 JavaScript 기반의 전용 클라이언트입니다.

2. 에이전트 설치

2.1 초기화

NetFUNNEL Browser 에이전트는 페이지 로드 시 초기화 코드를 통해 서비스에 적용됩니다. 서비스 로직보다 먼저 실행되어야 하므로 <head> 태그 상위에 배치하는 것이 좋습니다.

다음은 초기화 코드 예시입니다.

<html>
  <head>
    ...
    <script
      src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
      data-nf-client-id="{CLIENT_ID}"
      data-nf-network-timeout="3000"
      data-nf-retry-count="0"
      data-nf-custom-cookie-domain=""
      data-nf-use-network-recovery-mode="false"
      data-nf-storage-type="both"
      data-nf-return-key="true"
      data-nf-error-bypass="false"
      data-nf-use-netfunnel-template="true"
    ></script>
    ...
  </head>
</html>

NetFUNNEL Browser 에이전트는 다양한 부가 기능을 제공합니다. 부가 기능을 활성화하려면 초기화 코드에 설정값을 추가합니다. 적용 방식에 따라 사용할 수 있는 부가 기능이 다르니 아래 표를 참고하세요.

data 속성명	적용 방식	설명	조건
`data-nf-custom-cookie-domain`	URL 트리거 · 코드 기반	쿠키 저장 시 도메인 설정	기본: 빈 값
`data-nf-storage-type`	URL 트리거 · 코드 기반	브라우저 저장소 선택	기본: both
`data-nf-return-key`	URL 트리거	키 반납 처리	기본: true
`data-nf-use-network-recovery-mode`	코드 기반	네트워크 에러 시 대기실 유지 및 회복	기본: false
`data-nf-network-timeout`	코드 기반	네트워크 응답 최대 대기 시간	기본 3,000ms · 최대 10,000ms · 최소 100ms
`data-nf-retry-count`	코드 기반	네트워크 재시도 횟수	기본 0 · 최대 10 · 최소 0
`data-nf-error-bypass`	코드 기반	Error·NetworkError 대신 Success 상태값 반환	기본: false
`data-nf-use-netfunnel-template`	코드 기반	자체 커스텀 대기실 사용	기본: true
`data-nf-health-check-url`	코드 기반	네트워크 헬스 체크 주소	기본: 빈 값

3. 에이전트 적용

NetFUNNEL Browser 에이전트로 대기열 제어 지점을 설정하는 방식에는 URL 트리거 적용과 코드 기반 적용, 두 가지가 있습니다.

3.1 URL 트리거 적용

넷퍼넬 콘솔의 세그먼트 설정에서 트리거 규칙을 통해 적용합니다. 사용자가 접속한 페이지의 URL이 트리거 규칙과 매칭되면 대기열을 적용합니다. 넷퍼넬 콘솔에서 설정하므로 애플리케이션 재배포가 필요 없고, 대기열 적용 지점을 실시간으로 변경할 수 있습니다.

대기 전: 페이지 로드 → 에이전트 초기화 → 트리거 규칙 매치
대기 중: 넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 페이지로 이동
대기 후: 서비스 페이지 진입 → 넷퍼넬 키 반납

3.2 코드 기반 적용

서비스 중인 애플리케이션 코드에서 넷퍼넬이 제공하는 함수를 호출합니다. 대기열 적용 지점을 변경할 때마다 재배포가 필요하지만, 트래픽이 발생하기 전에 대기실을 노출하므로 트래픽을 사전에 효과적으로 제어할 수 있습니다.

대기 전: 페이지 로드 → 에이전트 초기화 → 시작 함수 실행
대기 중: 넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 노출
대기 후: Success 로직 실행 → 종료 함수 실행

기본 제어

시작 함수

대기를 적용하고 싶은 지점에서 함수를 호출하여 키를 발급하고 대기실을 노출시킵니다. 페이지 진입이나 이벤트 시작 부분에 적용합니다.

파라미터	타입	설명	필수
`projectKey`	String	NetFUNNEL 콘솔의 기본제어 프로젝트 키	O
`segmentKey`	String	NetFUNNEL 콘솔의 기본제어 세그먼트 키	O
`callback`	Function	대기실 이벤트 처리를 위한 사용자 정의 콜백 함수	O

nfStart({
    projectKey: "{PROJECT_KEY}",
    segmentKey: "{SEGMENT_KEY}"
}, function (response) {
    // 응답에 따라 콜백 함수를 구현합니다.
    nfCallback(response);
});

종료 함수

진입을 완료한 후 키 반납을 위해 사용합니다. 시작 함수 종료 후 또는 진입한 유저의 활동이 완료되는 지점에 적용합니다.

nfStop({
    projectKey: "{PROJECT_KEY}",
    segmentKey: "{SEGMENT_KEY}"
});

구간 제어

구간 제어란, 애플리케이션의 특정 구간에서 동시 접속자 수를 일정하게 유지하도록 제어하는 기능입니다. 시작 함수 호출 시 키를 발급하고, 종료 함수를 호출하기 전까지는 유저가 활동 구간에 있는 것으로 판단하여 다음 대기자를 진입시키지 않습니다. 종료 함수를 호출하면 키를 반납하고 다음 대기자가 진입합니다.

시작 함수

대기를 적용하고 싶은 지점에서 함수를 호출하여 키를 발급하고 대기실을 노출시킵니다. 페이지 진입이나 이벤트 시작 부분에 적용합니다.

파라미터	타입	설명	필수
`projectKey`	String	NetFUNNEL 콘솔의 기본제어 프로젝트 키	O
`segmentKey`	String	NetFUNNEL 콘솔의 기본제어 세그먼트 키	O
`callback`	Function	대기실 이벤트 처리를 위한 사용자 정의 콜백 함수	O

nfStartSection({
    projectKey: "{PROJECT_KEY}",
    segmentKey: "{SEGMENT_KEY}"
}, function (response) {
    // 응답에 따라 콜백 함수를 구현합니다.
    nfCallback(response);
});

종료 함수

진입을 완료한 후 키 반납을 위해 사용합니다. 진입한 유저의 활동 구간이 종료되는 지점에 적용합니다.

nfStopSection({
    projectKey: "{PROJECT_KEY}",
    segmentKey: "{SEGMENT_KEY}"
});

콜백 처리

기본 제어와 구간 제어 시작 함수의 두 번째 파라미터인 콜백 함수에서 넷퍼넬 서버의 응답을 받을 수 있습니다. 응답 결과에 따라 다양한 처리 로직을 수행할 수 있습니다.

status	statusCode	message	설명
Success	200	Success	대기열을 정상적으로 통과하여 서비스에 진입
Success	300	Bypass	구독·라이선스 만료 · 프로젝트·세그먼트 비활성화 · `data-nf-error-bypass=true` 설정
Success	303	Express	진입 성공 시 동작
Error	500	Server Error	존재하지 않는 프로젝트·세그먼트 키 사용 · 대기 중 세그먼트 삭제 · 서버 에러로 인한 응답 누락
NetworkError	1001	Network Not Connected	네트워크 연결 차단
NetworkError	1002	Network Timeout	네트워크 지연 · 유효하지 않은 대기실 html 주소 · 넷퍼넬 서버 다운
Block	301	Block	세그먼트 차단
IpBlock	302	Macro Block	블랙리스트 · BotManager Basic 활성화
Close	499	Canceled Waiting Room	기본 대기실의 취소 버튼 클릭
Close	498	Closed Blocking Room	차단실의 닫기 버튼 클릭
Close	497	Closed Macro Blocking Room	매크로 차단실의 닫기 버튼 클릭
Close	496	Closed PreWaiting Room	사전 대기실의 닫기 버튼 클릭
Close	495	Closed PostWaiting Room	사후 대기실의 닫기 버튼 클릭

function nfCallback(response) {
  const { status, statusCode, message } = response;

  switch (status) {
    case 'Success':
      // 진입 또는 우회 응답: 넷퍼넬 적용 이전의 원래 서비스 로직 실행
      // 예) 페이지 이동, 함수 실행, API 요청
      break;

    case 'Error':
      // 시스템 에러: 원활한 서비스 이용을 위해 원래 서비스 로직 실행
      break;

    case 'NetworkError':
      // 네트워크 에러: 원래 로직 실행 또는 안내 후 대기열 재진입
      break;

    case 'Block':
      // 진입 차단: 차단 안내 또는 무동작
      break;

    case 'IpBlock':
      // 반복 요청으로 차단: 차단 안내 또는 무동작
      break;

    case 'Close':
      // 대기실 닫기·취소 클릭: 취소 안내 또는 무동작
      break;

    default:
      console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
  }
}

4. 트리거 규칙 설정

대기열 제어 지점은 NetFUNNEL 콘솔의 세그먼트 트리거 규칙을 통해 설정할 수 있습니다. 사용자가 접속한 페이지의 URL과 트리거 규칙을 비교하여 일치하는 경우 대기열이 적용됩니다.

트리거 규칙 설정 방법은 트리거 규칙 문서를 참고하세요.