JavaScript 통합 가이드

1. 에이전트 소개

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

2. 에이전트 설치

2.1 초기화

NetFUNNEL JavaScript 에이전트는 페이지 로드 시 초기화 코드를 통해서 서비스에 적용됩니다. 따라서 서비스 로직보다 먼저 실행되야 하기 때문에 head 태그의 상위에 위치하는 것이 좋습니다.

warning

NetFUNNEL JavaScript 에이전트는 페이지의 모든 요소보다 우선적으로 로드되어야 하므로, <head> 태그 내 최상단에 배치하여 다른 스크립트나 리소스보다 먼저 실행되도록 해야 합니다.

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

UTI: URL 트리거 적용(URL Triggered Integration)

CBI: 코드 기반 적용(Code Based Integration)

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

HTML

<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>

3. 에이전트 적용

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

warning

NetFUNNEL JavaScript 에이전트를 설치한 고객은 두 가지 적용 방식을 사용할 수 있지만, 설정의 간소화와 관리의 용이성을 위해 한 가지만 사용하시기 바랍니다.

3.1 URL 트리거 적용

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

대기 전

페이지 로드 → 에이전트 초기화 → 트리거 규칙 매치

대기 중

넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 페이지로 이동

대기 후

서비스 페이지 진입 → 넷퍼넬 키 반납

3.2 코드 기반 적용

대기 전

페이지 로드 → 에이전트 초기화 → 시작 함수 실행

대기 중

넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 노출

대기 후

Success 로직 실행 → 종료 함수 실행

3.2.2 기본제어

시작 함수

대기를 적용하고 싶은 지점에서 함수를 호출하여 키를 발급하고 대기실을 노출시킵니다.

페이지 진입이나 이벤트 시작 부분에 적용합니다.

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

JavaScript

nfStart({
    projectKey: "{PROJECT_KEY}",
    segmentKey: "{SEGMENT_KEY}"
}, function(response) {
    // TODO: Implement callback function according to the response.
    nfCallback(response);
});

종료 함수

진입을 완료한 후 키 반납을 위해 사용합니다.

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

JavaScript

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

3.2.3 구간제어

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

시작 함수

대기를 적용하고 싶은 지점에서 함수를 호출하여 키를 발급하고 대기실을 노출시킵니다.

페이지 진입이나 이벤트 시작 부분에 적용합니다.

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

JavaScript

nfStartSection({
    projectKey: "{PROJECT_KEY}",
    segmentKey: "{SEGMENT_KEY}"
}, function(response) {
    // TODO: Implement callback function according to the response.
    nfCallback(response);
});

종료 함수

진입을 완료한 후 키 반납을 위해 사용합니다.

진입한 유저의 활동 구간이 종료되는 지점에 적용합니다.

JavaScript

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

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

info

상태값 Success, Error, NetworkError에 대해서는 필수적으로 처리를 해야 합니다. 그 외의 상태값은 처리하지 않아도 서비스에 영향이 없습니다.

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	사후 대기실의 닫기 버튼 클릭

JavaScript

function nfCallback(response) {
  const { status, statusCode, message } = response;
  
  switch(status) {
    case 'Success':
      // Entry or bypass response received; execute original service logic before NetFunnel application.
      // ex - Page navigation, function execution, API request
      break;
    
    case 'Error':
      // System error occurred; execute original service logic for smooth service usage.
      // ex - Page navigation, function execution, API request
      break;
      
    case 'NetworkError':
      // Network error occurred; execute original service logic or notify and re-enter queue.
      // ex - Page navigation, function execution, API request, alert("Network request failed, retrying.");
      break;
      
    case 'Block':
      // Entry status blocked; notify block or do nothing.
      // ex - alert("Access to this page is blocked.");
      break;
      
    case 'IpBlock':
      // Blocked due to repeated requests; notify block or do nothing.
      // ex - alert("Blocked due to repeated requests.");
      break;
      
    case 'Close':
      // Waiting room close or cancel button clicked; notify cancellation or do nothing.
      // ex - alert("Waiting has been canceled.");
      break;
      
    default:
      console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
  }
}

4. 트리거 규칙 설정

info

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

트리거 규칙 설정 방법은 트리거 규칙 설정 가이드를 참고하세요.