Skip to main content

JavaScript 퀵 가이드

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

1. 디렉터리 구조

이후 단계에서 구현하게 될 NetFUNNEL 적용 예제의 기본 디렉터리 구조입니다. 각 파일은 에이전트 초기화, 진입/종료 콜백 처리, UI 흐름 제어를 담당합니다.

├── page1.html // calls nfStart - entry request
└── page2.html // calls nfStop - entry complete handling

2. 에이전트 초기화

NetFUNNEL JavaScript 에이전트는 안정적인 동작을 위해 페이지 로드 시 우선적으로 실행되어야 합니다. 따라서 HTML head 태그의 상위에 위치하는 것이 좋습니다.

<html>
  <head>
    ...
    <script 
      src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
      data-nf-client-id="{CLIENT_ID}"
    ></script>
    ...
  </head>
</html>

2.2 트리거 규칙 기반 적용

NetFUNNEL 콘솔의 세그먼트 설정에서 트리거 규칙을 통해 대기열을 제어하고자 하는 URL을 설정할 수 있습니다.

2.3 코드 기반 적용

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

3. 콜백 함수

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

  • Success: 진입 또는 우회 응답을 받았기 때문에 페이지 이동이나 함수 실행과 같은 기존의 서비스 로직을 실행합니다.
  • Error: 시스템 에러가 발생한 경우로, 원활한 서비스 이용을 위해 Success와 마찬가지로 기존의 서비스 로직을 실행합니다.
  • NetworkError: 네트워크 장애가 발생한 경우로, 원활한 사용자의 경험을 위해 기존의 서비스 로직을 실행하게 할 수 있지만, 네트워크 상태를 변경하는 등 악용의 가능성이 있기 때문에 다시 대기하도록 할 수도 있습니다.
function nfCallback(response) {
  const { status, statusCode, message } = response;
  
  switch(status) {
    case 'Success':
      // Navigate to the target page
      window.location.href = "target_page";
      break;
      
    case 'Error':
      // Execute a function for the existing logic
      callFunction();
      break;
      
    case 'NetworkError':
      // Notify network error and retry
      alert("Network request failed, retrying.");
      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(구간제어)은 대기 완료 후 서버에 진입 키를 반납하기 위한 함수입니다. 진입 키를 서버에 반납하여 다음 사용자가 진입할 수 있도록 하며, 일반적으로 서비스 진입 직후 실행합니다.

info

종료 함수는 콜백 함수를 처리하지 않아도 됩니다.

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

6. 코드 기반 적용 예시

6.1 Page1에서 Page2로 이동

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

시작 함수(nfStart, nfStartSection) 적용 예시

page1.html
<!DOCTYPE html>
<html lang="en">
  ...
  <body>
    <h1>Page 1</h1>
    <a href="/page2.html">Go to Page 2</a>
  </body>
</html>

종료 함수(nfStop, nfStopSection) 적용 예시

page2.html
<html>
  ...
  <body>
    <h1>Page 2</h1>
  </body>
</html>

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

종료 함수는 로그인 및 서비스 로직 이후 적절한 위치에서 실행해주시면 됩니다.

시작 함수(nfStart, nfStartSection) 적용 예시

login.html
<html>
  ...
  <body>
    <button onclick="requestLogin()">Login</button>
    <script>
      function requestLogin() {
        fetch('/api/login', { method: 'GET' });
      }
    </script>
  </body>
</html>

종료 함수(nfStop, nfStopSection) 적용 예시

종료 함수는 로그인 및 서비스 로직 이후 적절한 위치에서 실행해주시면 됩니다.