API 참조

NetFUNNEL JavaScript 에이전트 함수, 콜백 및 응답 형식에 대한 완전한 참조입니다.

---

목차

• 기본 제어 함수
• 구간 제어 함수
• 콜백 함수
• 응답 객체 스키마
• 상태 코드 참조
• 모범 사례

---

기본 제어 함수

기본 제어는 서비스의 진입 속도를 제한합니다. 시작 함수가 호출되면 키가 발급되고 대기실이 나타납니다. 중지 함수가 호출되면 키가 반환됩니다.

nfStart

목적: 동작 시작 시 키를 발급하고 대기실을 표시합니다.

함수 시그니처:

nfStart(keys, callback)

매개변수:

매개변수	유형	설명	필수
keys	Object	프로젝트 및 세그먼트 키를 포함하는 객체	예
keys.projectKey	String	콘솔의 기본 제어 프로젝트 키	예
keys.segmentKey	String	콘솔의 기본 제어 세그먼트 키	예
callback	Function	VWR 이벤트를 처리하는 사용자 정의 콜백	예

반환값: undefined

예제:

nfStart({
  projectKey: "service_1",
  segmentKey: "segKey_8612"
}, function(response) {
  // 응답 처리 - 자세한 내용은 콜백 함수 섹션 참조
  if (response.status === 'Success') {
    // 로직 진행
    console.log('Entry granted!');
  }
});

콜백 처리: 자세한 응답 처리 내용은 콜백 함수 섹션을 참조하세요.

nfStop

목적: 진입이 완료된 후 키를 반환합니다.

함수 시그니처:

nfStop(keys)

매개변수:

매개변수	유형	설명	필수
keys	Object	프로젝트 및 세그먼트 키를 포함하는 객체	예
keys.projectKey	String	콘솔의 기본 제어 프로젝트 키	예
keys.segmentKey	String	콘솔의 기본 제어 세그먼트 키	예

반환값: undefined

예제:

nfStop({
  projectKey: "service_1",
  segmentKey: "segKey_8612"
});

자동 반환 타임아웃

중지 함수를 실행하지 않으면 세그먼트 타임아웃 설정에 따라 키가 자동으로 반환됩니다 (기본 타임아웃: 20초).

---

구간 제어 함수

구간 제어는 특정 애플리케이션 구간의 동시 사용자 수를 고정 값으로 유지합니다. 시작 함수가 호출되면 키가 발급됩니다. 중지 함수가 호출될 때까지 사용자는 활성 구간에 있는 것으로 간주되며, 대기열의 다음 사용자는 허용되지 않습니다.

nfStartSection

목적: 구간 제어를 위해 키를 발급하고 대기실을 표시합니다.

함수 시그니처:

nfStartSection(keys, callback)

매개변수:

매개변수	유형	설명	필수
keys	Object	프로젝트 및 세그먼트 키를 포함하는 객체	예
keys.projectKey	String	콘솔의 구간 제어 프로젝트 키	예
keys.segmentKey	String	콘솔의 구간 제어 세그먼트 키	예
callback	Function	VWR 이벤트를 처리하는 사용자 정의 콜백	예

반환값: undefined

예제:

nfStartSection({
  projectKey: "service_1",
  segmentKey: "section_segKey_1234"
}, function(response) {
  // 응답 처리 - 자세한 내용은 콜백 함수 섹션 참조
  if (response.status === 'Success') {
    // 사용자가 구간에 진입함
    console.log('Section entry granted!');
  }
});

콜백 처리: 자세한 응답 처리 내용은 콜백 함수 섹션을 참조하세요.

nfStopSection

목적: 사용자가 활성 구간을 종료할 때 키를 반환합니다.

함수 시그니처:

nfStopSection(keys)

매개변수:

매개변수	유형	설명	필수
keys	Object	프로젝트 및 세그먼트 키를 포함하는 객체	예
keys.projectKey	String	콘솔의 구간 제어 프로젝트 키	예
keys.segmentKey	String	콘솔의 구간 제어 세그먼트 키	예

반환값: undefined

예제:

nfStopSection({
  projectKey: "service_1",
  segmentKey: "section_segKey_1234"
});

구간 제어 동작

중지 함수를 실행하지 않으면 사용자가 활성 구간에 계속 머물러 있는 것으로 간주되어 다음 사용자의 허용이 지연될 수 있습니다.

---

콜백 함수

기본/구간 제어 시작 함수(nfStart 및 nfStartSection)의 콜백 함수(두 번째 매개변수)에서 NetFUNNEL 서버의 응답을 받을 수 있습니다. 응답 결과를 기반으로 다양한 처리 로직을 수행할 수 있습니다.

필수 상태 처리

다음 세 가지 상태를 반드시 처리해야 합니다:

• Success: 진입 허용 또는 우회 모드
• Error: 시스템 오류 발생
• NetworkError: 네트워크 연결 문제

샘플 콜백 구현

function nfCallback(response) {
  const { status, statusCode, message } = response;
  
  switch (status) {
    case 'Success':
      // 진입 또는 우회 수신 — 원래 서비스 로직 실행
      console.log('User can proceed!');
      // 예: 페이지로 이동, 함수 실행, API 호출
      break;
      
    case 'Error':
      // 시스템 오류 발생 — 원활한 UX를 위해 원래 로직 실행
      console.log(`System error: ${message}`);
      // 예: 페이지로 이동, 함수 실행, API 호출
      break;
      
    case 'NetworkError':
      // 네트워크 오류 발생 — 재귀 호출로 재시도
      console.log(`Network error: ${message}`);
      // NetFUNNEL 시작 함수를 재시도하기 위한 재귀 호출
      nfStart(keys, nfCallback); // 또는 nfStartSection(keys, nfCallback)
      break;
      
    case 'Block':
      // 진입 상태가 Block — 사용자에게 알림
      console.log('Access blocked');
      // 예: alert("This page is blocked for entry.");
      break;
      
    case 'IpBlock':
      // 반복 요청으로 인한 차단
      console.log('IP blocked');
      // 예: alert("You have been blocked due to repeated requests.");
      break;
      
    case 'Close':
      // 사용자가 대기실에서 닫기/취소를 클릭함
      console.log('Waiting canceled by user');
      // 예: alert("Waiting has been canceled.");
      break;
      
    default:
      console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
  }
}

---

응답 객체 스키마

콜백에 전달되는 response 객체는 다음 필드를 포함합니다:

필드	유형	예제 / 설명
status	String	Success / Error / NetworkError / Block / IpBlock / Close
statusCode	Number	200, 201, 300, 303, 500, 1001, 1002, 301, 302, 49x 등
message	String	Success, Bypass, Express, Server Error, Network Timeout 등
key	String	발급된 진입 키 (ID)

예제 응답 객체:

// Success 응답
{
  status: "Success",
  statusCode: 200,
  message: "Success",
  key: "key_12345"
}

// Bypass 응답
{
  status: "Success", 
  statusCode: 300,
  message: "Bypass",
  key: "key_12345"
}

// 네트워크 오류 응답
{
  status: "NetworkError",
  statusCode: 1002,
  message: "Network Timeout",
  key: "key_12345"
}

---

상태 코드 참조

가능한 모든 상태 코드와 그 의미에 대한 완전한 참조입니다.

상태	StatusCode	Message	설명
Success	200	Success	대기열을 성공적으로 통과하고 서비스에 진입함
	300	Bypass	구독/라이선스 만료, 프로젝트/세그먼트 비활성화, data-nf-error-bypass=true
	303	Express	Express 진입 성공
Error	500	Server Error	존재하지 않는 키 사용, 대기 중 세그먼트 삭제, 서버 오류
NetworkError	1001	Network Not Connected	네트워크 연결 차단
	1002	Network Timeout	네트워크 지연, 잘못된 대기실 HTML, 서버 다운
Block	301	Block	세그먼트가 차단 상태임
IpBlock	302	Macro Block	블랙리스트, BotManager Basic 활성화
Close	499	Canceled Waiting Room	기본 대기실에서 취소/닫기 버튼을 클릭함
	498	Closed Blocking Room	차단실을 닫음
	497	Closed Macro Blocking Room	매크로 차단실을 닫음
	496	Closed PreWaiting Room	사전 대기실을 닫음
	495	Closed PostWaiting Room	사후 대기실을 닫음

---

모범 사례

함수 가용성 확인

NetFUNNEL 함수를 호출하기 전에 항상 사용 가능한지 확인하세요:

if (typeof window.nfStart === 'function') {
  nfStart(keys, callback);
} else {
  // 대체 로직
  console.log('NetFUNNEL not available, proceeding without protection');
  performOriginalLogic();
}

키 일치

시작 및 중지 함수는 동일한 키를 사용해야 합니다:

const keys = { 
  projectKey: 'service_1', 
  segmentKey: 'segKey_8612' 
};

// 시작
nfStart(keys, callback);

// 중지 (동일한 키 사용해야 함)
nfStop(keys);

키 반환 전략

사용자가 성공적으로 진입한 경우에만 키를 반환하세요:

function performAction() {
  nfStart(keys, function(response) {
    if (response.status === 'Success') {
      doSomething();
    }
  });
}

// 페이지 로드 시 키 반환 (페이지 탐색 사례용)
window.addEventListener('load', () => {
  if (typeof window.nfStop === 'function') {
    nfStop(keys);
  }
});

일반적인 통합 패턴

버튼 클릭 보호

document.getElementById('login-button').addEventListener('click', () => {
  if (typeof window.nfStart === 'function') {
    nfStart({
      projectKey: 'service_1',
      segmentKey: 'login_segKey'
    }, function(response) {
      // 자세한 응답 처리 내용은 콜백 함수 섹션 참조
      if (response.status === 'Success') {
        performLogin();
      } else {
        handleError(response);
      }
    });
  } else {
    performLogin(); // 대체
  }
});

function performLogin() {
  // 로그인 로직 여기에 작성
  fetch('/api/login', { /* ... */ })
    .then(() => {
      // 로그인 성공 후 키 반환
      if (typeof window.nfStop === 'function') {
        nfStop({
          projectKey: 'service_1',
          segmentKey: 'login_segKey'
        });
      }
    })
    .catch(() => {
      // 오류 발생 시에도 키 반환
      if (typeof window.nfStop === 'function') {
        nfStop({
          projectKey: 'service_1',
          segmentKey: 'login_segKey'
        });
      }
    });
}

재귀 호출을 사용한 NetworkError 처리

NetworkError 상태의 경우 NetFUNNEL 시작 함수를 재시도하기 위해 재귀 호출을 구현해야 합니다. 이렇게 하면 네트워크 문제가 일시적인 경우 더 나은 사용자 경험을 보장할 수 있습니다.

// 재귀 호출을 사용한 기본 제어 NetworkError 처리
function startWithRetry(keys) {
  nfStart(keys, function(response) {
    switch (response.status) {
      case 'Success':
        // 원래 로직 진행
        performAction();
        break;
        
      case 'NetworkError':
        console.log('Network error, retrying...');
        // 재시도를 위한 재귀 호출
        startWithRetry(keys);
        break;
        
      case 'Error':
        console.log('System error, proceeding without protection');
        performAction();
        break;
        
      default:
        console.log(`Unexpected status: ${response.status}`);
        performAction();
    }
  });
}

// 재귀 호출을 사용한 구간 제어 NetworkError 처리
function startSectionWithRetry(keys) {
  nfStartSection(keys, function(response) {
    switch (response.status) {
      case 'Success':
        // 사용자가 구간에 진입함
        showCheckoutForm();
        break;
        
      case 'NetworkError':
        console.log('Network error, retrying section entry...');
        // 재시도를 위한 재귀 호출
        startSectionWithRetry(keys);
        break;
        
      case 'Error':
        console.log('System error, proceeding without section protection');
        showCheckoutForm();
        break;
        
      default:
        console.log(`Unexpected status: ${response.status}`);
        showCheckoutForm();
    }
  });
}

// 사용 예제
const keys = {
  projectKey: 'service_1',
  segmentKey: 'segKey_8612'
};

// 재시도 로직과 함께 시작
startWithRetry(keys);

function performAction() {
  // 비즈니스 로직 여기에 작성
  console.log('Performing protected action...');
  
  // 동작 완료 시 키 반환
  nfStop(keys);
}

function showCheckoutForm() {
  // 체크아웃 폼 로직 여기에 작성
  console.log('Showing checkout form...');
}

다단계 구간 제어

// 구간 시작 (예: 체크아웃 프로세스)
function startCheckout() {
  nfStartSection({
    projectKey: 'service_1',
    segmentKey: 'checkout_segKey'
  }, function(response) {
    // 자세한 응답 처리 내용은 콜백 함수 섹션 참조
    if (response.status === 'Success') {
      showCheckoutForm();
    }
  });
}

// 구간 종료 (예: 결제 완료 후)
function completeCheckout() {
  // 체크아웃 완료 로직
  processPayment()
    .then(() => {
      // 성공적인 완료 후 키 반환
      nfStopSection({
        projectKey: 'service_1',
        segmentKey: 'checkout_segKey'
      });
    });
}

---

관련 문서

• 코드 기반 통합: 예제가 포함된 구현 가이드
• 초기화 옵션 참조: 모든 data-attribute 옵션
• 문제 해결: 일반적인 문제 및 해결 방법