통합 가이드

1. 에이전트 소개

NetFUNNEL React Native 에이전트는 NetFUNNEL 서버와 통신하는 전용 클라이언트입니다.

2. 에이전트 설치

2.1 최소 요구 사항

• react-native 0.70.0 이상
• react-native-webview 13.0.0 이상
• @react-native-async-storage/async-storage 1.23.1 이상

2.2 패키지 설치

package.json의 dependencies에 NetFUNNEL React Native 에이전트를 추가합니다.

package.json

{
  "dependencies": {
    "netfunnel-rn-agent": "https://agent-lib.stclab.com/agents/static/rn/netfunnel-rn-agent-latest.tgz"
  }
}

프로젝트 루트에서 패키지를 설치합니다. 에이전트가 사용하는 react-native-webview와 async-storage가 프로젝트에 없다면 함께 설치합니다.

npm install
npm install react-native-webview @react-native-async-storage/async-storage

참고

iOS에서는 네이티브 모듈 연결을 위해 ios 디렉터리에서 pod install을 실행해야 할 수 있습니다.

2.3 초기화

NetFUNNEL React Native 에이전트는 앱 실행 시 한 번 초기화되어야 합니다. 앱 진입점(예: index.js 또는 App.tsx 최상단)에서 초기화 함수를 호출합니다.

주의

초기화하지 않고 시작 함수를 호출하면 Error(500)가 반환됩니다. 반드시 앱 실행 시점에 초기화하세요.

index.js

import { AppRegistry } from 'react-native';
import Netfunnel from 'netfunnel-rn-agent';
import App from './App';
import { name as appName } from './app.json';

Netfunnel.initialize({
  clientId: '{CLIENT_ID}',
  serverUrl: '{SERVER_URL}',
  errorUrl: '{ERROR_URL}',
  networkTimeout: 3000,
  retryCount: 0,
  printLog: false,
  errorBypass: false,
  useNetfunnelTemplate: true,
  userId: '{USER_ID}',
  useNetworkRecoveryMode: false,
});

AppRegistry.registerComponent(appName, () => App);

참고

{CLIENT_ID}는 NetFUNNEL 콘솔 우측 상단의 프로필 아이콘 > 통합 자격 증명 메뉴에서 확인합니다.

NetFUNNEL React Native 에이전트는 다양한 부가 기능을 제공합니다. 부가 기능을 활성화하려면 초기화 함수에 설정값을 추가합니다.

파라미터	타입	설명	조건
clientId	string	클라이언트 고유 식별자	필수 · 빈 문자열 불가
serverUrl	string	NetFUNNEL 서버 주소	기본: 기본 주소 사용
errorUrl	string	NetFUNNEL 에러 페이지 HTML 주소	기본: 기본 주소 사용
networkTimeout	number	네트워크 응답 최대 대기 시간	기본 3,000ms · 최대 10,000ms · 최소 100ms
retryCount	number	네트워크 재시도 횟수	기본 0 · 최대 10 · 최소 0
printLog	boolean	디버그 로그 출력	기본: false
errorBypass	boolean	Error·NetworkError 대신 Success 상태값 반환	기본: false
useNetfunnelTemplate	boolean	NetFUNNEL 대기실 사용 (false면 커스텀 대기실)	기본: true
userId	string	반복 요청 차단의 ID 기준 차단·허용에 사용할 사용자 ID	기본: null
useNetworkRecoveryMode	boolean	네트워크 에러 시 대기실 유지 및 회복	기본: false

2.4 대기실 컴포넌트 배치

대기실은 Netfunnel.WebViewComponent에 표시됩니다. 앱 내비게이션과 관계없이 화면 전체에 대기실을 띄울 수 있도록, 앱 루트 View 안에서 NavigationContainer 다음에 배치합니다.

App.tsx

import React from 'react';
import { View } from 'react-native';
import { NavigationContainer } from '@react-navigation/native';
import Netfunnel from 'netfunnel-rn-agent';

export default function App() {
  return (
    <View style={{ flex: 1 }}>
      <NavigationContainer>
        {/* 앱 화면 구성 */}
      </NavigationContainer>
      <Netfunnel.WebViewComponent />
    </View>
  );
}

주의

Netfunnel.WebViewComponent를 배치하지 않으면 시작 함수를 호출해도 대기실이 표시되지 않습니다.

3. 에이전트 적용

React Native 에이전트는 코드 기반 적용을 지원합니다. 대기열을 적용할 화면에서 시작 함수를 호출하고, 진입이 완료된 시점에 종료 함수를 호출합니다. 대기열 적용 지점을 바꿀 때마다 앱 배포가 필요하지만, 트래픽이 발생하기 전에 대기실을 노출하므로 트래픽을 사전에 효과적으로 제어할 수 있습니다.

참고

projectKey와 segmentKey는 NetFUNNEL 콘솔의 프로젝트 탭에서 확인합니다.

3.1 기본 제어

시작 함수

대기를 적용하고 싶은 지점에서 함수를 호출하여 키를 발급하고 대기실을 노출시킵니다. 화면 진입이나 이벤트 시작 부분에 적용합니다.

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

Netfunnel.nfStart('{PROJECT_KEY}', '{SEGMENT_KEY}', function (response) {
  // 응답에 따라 콜백 함수를 구현합니다.
  nfCallback(response);
});

종료 함수

진입을 완료한 후 키 반납을 위해 사용합니다. 진입 성공 후 또는 진입한 유저의 활동이 완료되는 지점에 적용합니다.

파라미터	타입	설명	필수
projectKey	string	NetFUNNEL 콘솔의 프로젝트 키	O
segmentKey	string	NetFUNNEL 콘솔의 세그먼트 키	O

Netfunnel.nfStop('{PROJECT_KEY}', '{SEGMENT_KEY}');

참고

종료 함수를 호출하지 않으면 세그먼트의 타임아웃 설정에 따라 진입 키가 자동으로 반납됩니다.

3.2 구간 제어

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

시작 함수

구간이 시작되는 지점에서 호출합니다. 파라미터는 기본 제어의 시작 함수와 같습니다.

Netfunnel.nfStartSection('{PROJECT_KEY}', '{SEGMENT_KEY}', function (response) {
  nfCallback(response);
});

종료 함수

진입한 유저의 활동 구간이 종료되는 지점에서 호출합니다. 파라미터는 기본 제어의 종료 함수와 같습니다.

Netfunnel.nfStopSection('{PROJECT_KEY}', '{SEGMENT_KEY}');

주의

구간 제어에서 종료 함수를 호출하지 않으면 사용자가 계속 구간 안에 있는 것으로 집계되어, 다음 대기자의 진입이 늦어집니다.

3.3 콜백 처리

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

참고

상태값 Success, Error, NetworkError는 반드시 처리해야 합니다. 그 외 상태값은 처리하지 않아도 서비스에 영향이 없습니다.

status	statusCode	message	설명
Success	200	Success	대기열을 정상적으로 통과하여 서비스에 진입
Success	300	Bypass	구독·라이선스 만료 · 프로젝트·세그먼트 비활성화 · errorBypass=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	사후 대기실의 닫기 버튼 클릭

nfCallback 예시

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

  switch (status) {
    case 'Success':
      // 진입 또는 우회 응답: 넷퍼넬 적용 이전의 원래 서비스 로직 실행
      // 예) 화면 이동, 함수 실행, API 요청
      break;

    case 'Error':
      // 시스템 에러: 원활한 서비스 이용을 위해 원래 서비스 로직 실행
      break;

    case 'NetworkError':
      // 네트워크 에러: 원래 로직 실행 또는 안내 후 대기열 재진입
      break;

    case 'Block':
      // 진입 차단: 차단 안내 또는 무동작
      break;

    case 'IpBlock':
      // 반복 요청으로 차단: 차단 안내 또는 무동작
      break;

    case 'Close':
      // 대기실 닫기·취소 클릭: 취소 안내 또는 무동작
      break;

    default:
      console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
  }
}