퀵가이드

이 퀵가이드는 NetFUNNEL Browser 에이전트를 처음 적용하는 개발자가 빠르게 시작할 수 있도록 필수 구현 사항을 간략히 안내합니다.

1. 디렉터리 구조

아래는 예제의 기본 디렉터리 구조입니다. 각 파일은 에이전트 초기화, 진입/종료 콜백 처리, UI 흐름 제어를 담당합니다.

├── page1.html   // nfStart 호출 - 진입 요청
└── page2.html   // nfStop 호출 - 진입 완료 처리

2. 에이전트 초기화

Browser 에이전트는 안정적인 동작을 위해 페이지 로드 시 우선 실행되어야 합니다. 따라서 HTML <head> 태그 상위에 배치하는 것이 좋습니다. (자세한 초기화 코드는 통합 가이드를 참고하세요.)

2.1 트리거 규칙 기반 적용

NetFUNNEL 콘솔의 세그먼트 설정에서 트리거 규칙으로 대기열을 제어할 URL을 지정합니다. 코드 수정 없이 콘솔에서 적용 지점을 관리합니다.

2.2 코드 기반 적용

애플리케이션에서 대기열을 적용할 지점에 시작 함수를, 진입이 완료된 지점에 종료 함수를 작성하여 진입 키를 반납합니다.

3. 콜백 함수

시작 함수(nfStart, nfStartSection)의 두 번째 파라미터인 콜백 함수에서 넷퍼넬 서버의 응답을 받습니다. 응답은 상태값(status), 상태 코드(statusCode), 메시지(message)를 포함하며, 상태값에 따라 분기 처리합니다.

Success: 진입 또는 우회 응답. 페이지 이동·함수 실행 등 기존 서비스 로직을 실행합니다.
Error: 시스템 에러. 원활한 이용을 위해 Success와 동일하게 기존 로직을 실행합니다.
NetworkError: 네트워크 장애. 기존 로직을 실행하거나, 악용 방지를 위해 다시 대기하도록 처리할 수 있습니다.

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

  switch (status) {
    case 'Success':
      // 대상 페이지로 이동
      window.location.href = 'target_page';
      break;

    case 'Error':
      // 기존 서비스 로직 실행
      callFunction();
      break;

    case 'NetworkError':
      // 네트워크 에러 안내 후 재시도
      alert('네트워크 요청에 실패했습니다. 다시 시도합니다.');
      nfStart({
        projectKey: '{PROJECT_KEY}',
        segmentKey: '{SEGMENT_KEY}'
      }, function (response) {
        nfCallback(response);
      });
      break;

    default:
      console.log(`[NF] ${JSON.stringify(response)}`);
  }
}

4. 시작 함수

nfStart(기본 제어), nfStartSection(구간 제어)는 대기 상태를 감지하고 필요 시 대기실을 띄우는 함수입니다.

nfStart({
  projectKey: '{PROJECT_KEY}',
  segmentKey: '{SEGMENT_KEY}'
}, function (response) {
  nfCallback(response);
});

5. 종료 함수

nfStop(기본 제어), nfStopSection(구간 제어)은 대기 완료 후 서버에 진입 키를 반납하는 함수입니다. 키를 반납해 다음 사용자가 진입할 수 있게 하며, 일반적으로 서비스 진입 직후 실행합니다.

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

6. 코드 기반 적용 예시

6.1 Page1에서 Page2로 이동

page1에서 page2로 이동하는 버튼에서 시작 함수를 호출해 대기열을 적용하고, Success 응답을 받으면 page2로 이동합니다. page2가 로드되면 종료 함수를 호출해 키를 반납합니다. (기본 제어와 구간 제어의 적용 방식은 동일합니다.)

<a href="#" onclick="nfStartOnClick()">Go to Page 2</a>

<script>
  function nfStartOnClick() {
    nfStart(
      {
        projectKey: '{PROJECT_KEY}',
        segmentKey: '{SEGMENT_KEY}'
      },
      function (response) {
        nfCallback(response);
      }
    );
  }

  function nfCallback(response) {
    const { status } = response;
    switch (status) {
      case 'Success':
      case 'Error':
        // 진입·우회·시스템 에러 응답 시 page2로 이동
        window.location.href = '/page2.html';
        break;
    }
  }
</script>

<script>
  // 페이지 로드 후 진입 키 반납
  nfStop({
    projectKey: '{PROJECT_KEY}',
    segmentKey: '{SEGMENT_KEY}'
  });
</script>

6.2 하나의 페이지 안에서 함수를 실행

한 페이지 안에서 시작 함수 호출 후, 로그인 및 서비스 로직을 처리한 뒤 적절한 위치에서 종료 함수를 실행합니다.