본문으로 건너뛰기
버전: 4.6.1-saas

API 참조

NetFUNNEL React Native Agent 함수, 콜백 및 응답 형식에 대한 완전한 참조입니다.

기본 제어 함수​

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

Netfunnel.nfStart​

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

함수 시그니처:

Netfunnel.nfStart(projectKey, segmentKey, callback)

매개변수:

매개변수유형설명
projectKeyString콘솔의 기본 제어 프로젝트 키
segmentKeyString콘솔의 기본 제어 세그먼트 키
callbackFunction대기실 이벤트 처리를 위한 사용자 정의 콜백 함수

반환값: undefined

예제:

Netfunnel.nfStart("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", function(response) {
  // 응답 처리 - 콜백 함수 섹션 참조
  nfCallback(response);
});

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

Netfunnel.nfStop​

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

함수 시그니처:

Netfunnel.nfStop(projectKey, segmentKey)

매개변수:

매개변수유형설명
projectKeyString콘솔의 기본 제어 프로젝트 키
segmentKeyString콘솔의 기본 제어 세그먼트 키

반환값: undefined

예제:

Netfunnel.nfStop("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}");
자동 반납 타임아웃

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

구간 제어 함수​

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

Netfunnel.nfStartSection​

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

함수 시그니처:

Netfunnel.nfStartSection(projectKey, segmentKey, callback)

매개변수:

매개변수유형설명
projectKeyString콘솔의 구간 제어 프로젝트 키
segmentKeyString콘솔의 구간 제어 세그먼트 키
callbackFunction대기실 이벤트 처리를 위한 사용자 정의 콜백 함수

반환값: undefined

예제:

Netfunnel.nfStartSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", function(response) {
  // 응답 처리 - 콜백 함수 섹션 참조
  nfCallback(response);
});

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

Netfunnel.nfStopSection​

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

함수 시그니처:

Netfunnel.nfStopSection(projectKey, segmentKey)

매개변수:

매개변수유형설명
projectKeyString콘솔의 구간 제어 프로젝트 키
segmentKeyString콘솔의 구간 제어 세그먼트 키

반환값: undefined

예제:

Netfunnel.nfStopSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}");
구간 제어 동작

중지 함수를 실행하지 않으면 사용자는 활성 구간에 남아있는 것으로 간주되며, 다음 사용자의 허용이 지연될 수 있습니다.

콜백 함수​

기본/구간 제어 시작 함수의 콜백 함수(세 번째 매개변수)에서 NetFUNNEL 서버로부터 응답을 받을 수 있습니다. 응답 결과에 따라 다양한 처리 로직을 수행할 수 있습니다.

필수 상태 처리​

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

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

Success, Error, NetworkError 외의 상태값은 처리하지 않아도 서비스에 영향이 없습니다.

샘플 콜백 구현​

function nfCallback(response) {
  const { status, statusCode, message } = response;
  switch(status) {
    case 'Success':
      // 진입 또는 우회 응답을 받은 경우로, 넷퍼넬을 적용하기 전의 기존 서비스 로직을 실행합니다.
      // ex - 페이지 이동, 함수 실행, API 요청
      break;
    case 'Error':
      // 시스템 에러가 발생한 경우로, 원활한 서비스 이용을 위해 일반적으로 Success와 동일하게 기존 서비스 로직을 실행합니다.
      // ex - 페이지 이동, 함수 실행, API 요청
      break;
    case 'NetworkError':
      // 네트워크 에러가 발생한 경우로, 기존 서비스 로직을 실행하거나 알림 후 다시 대기열에 진입하도록 합니다.
      // ex - 페이지 이동, 함수 실행, API 요청, modal("네트워크가 불안정합니다. 다시시도 하시겠습니까? Y/N");
      break;
    case 'Block':
      // 진입 상태가 차단인 경우로, 차단을 알리거나 아무 처리하지 않아도 됩니다.
      break;
    case 'IpBlock':
      // 반복 요청으로 인해 차단된 경우로, 차단을 알리거나 아무 처리하지 않아도 됩니다.
      break;
    case 'Close':
      // 대기실의 닫기 또는 취소버튼을 클릭한 경우로, 대기 취소를 알리거나 아무 처리하지 않아도 됩니다.
      // ex - alert("대기를 취소하였습니다.");
      break;
    default:
      console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
  }
}

응답 객체 스키마​

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

필드유형예제 / 설명
statusStringSuccess / Error / NetworkError / Block / IpBlock / Close
statusCodeNumber200, 201, 300, 303, 500, 1001, 1002, 301, 302, 49x 등
messageStringSuccess, Bypass, Express, Server Error, Network Timeout 등
keyString발급된 진입 키(ID)

예제 응답 객체:

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

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

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

상태 코드 참조​

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

statusstatusCodemessage설명
Success200Success대기열을 정상적으로 통과하여 서비스에 진입
300Bypass구독/라이선스 만료
프로젝트/세그먼트 비활성화
data-nf-error-bypass=true로 설정
303Express진입 성공 시 동작
Error500Server Error존재하지 않는 프로젝트/세그먼트 키 사용
대기 중 세그먼트 삭제
서버 에러로 인한 응답 누락
NetwrokError1002Network Timeout네트워크 지연
유효하지 않은 대기실 html 주소
넷퍼넬 서버 다운
Block301Block세그먼트 차단
IpBlock302Macro Block블랙리스트
BotManager Basic 활성화
Close499Canceled Waiting Room기본 대기실의 취소 버튼 클릭
498Closed Blocking Room차단실의 닫기 버튼 클릭
497Closed Macro Blocking Room매크로 차단실의 닫기 버튼 클릭
496Closed PreWaiting Room사전 대기실의 닫기 버튼 클릭
495Closed PostWaiting Room사후 대기실의 닫기 버튼 클릭

모범 사례​

중앙 집중식 구성​

// 키를 한 곳에 저장
const NETFUNNEL_CONFIG = {
  projectKey: 'service_1',
  segmentKey: 'segKey_8612'
};

// 모든 곳에서 동일한 구성 사용
Netfunnel.nfStart(
  NETFUNNEL_CONFIG.projectKey,
  NETFUNNEL_CONFIG.segmentKey,
  callback
);

Netfunnel.nfStop(
  NETFUNNEL_CONFIG.projectKey,
  NETFUNNEL_CONFIG.segmentKey
);

완전한 오류 처리​

function handleNetFunnelResponse(response, businessLogic) {
  switch (response.status) {
    case 'Success':
      businessLogic(); // 로직 진행
      break;
    case 'Error':
      // 시스템 오류 - 서비스 실행 유지를 위해 계속 진행
      console.error('NetFUNNEL 시스템 오류:', response.message);
      businessLogic();
      break;
    case 'NetworkError':
      // 네트워크 문제 - 계속 진행하거나 재시도
      console.log(`NetFUNNEL 네트워크 오류: ${response.message}`);
      businessLogic(); // 계속 진행하거나 재시도 로직 구현
      break;
    case 'Block':
      Alert.alert('서비스 사용 불가', '이 서비스는 일시적으로 사용할 수 없습니다.');
      break;
    case 'IpBlock':
      Alert.alert('액세스 거부', '이 문제가 계속되면 지원팀에 문의하세요.');
      break;
    case 'Close':
      // 사용자가 취소함 - 작업 필요 없음
      break;
  }
}

키 반환​

// 성공적인 작업 후 키 반환
try {
  await performAction();
  Netfunnel.nfStop(projectKey, segmentKey);
} catch (error) {
  console.error('작업 실패:', error);
  // 오류 발생 시에도 키 반환
  Netfunnel.nfStop(projectKey, segmentKey);
}

관련 문서​