React Native Agent
개요
NetFUNNEL React Native 에이전트는 NetFUNNEL 서버와 통신하는 전용 클라이언트입니다.
최소 요구 사항
- react-native 0.70.0 버전 이상
- react-native-webview 13.0.0 버전 이상
- react-native-async-storage/async-storage 1.23.1 버전 이상
에이전트 동작 흐름
대기열 제어 지점은 NetFUNNEL 콘솔의 세그먼트 트리거 규칙을 통해 설정할 수 있습니다. 사용자가 접속한 페이지의 URL과 트리거 규칙을 비교하여 일치하는 경우 대기열이 적용됩니다.
대기 전: 페이지 로드 → 에이전트 초기화 → 트리거 규칙 매치 대기 중: 넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 페이지로 이동 대기 후: 서비스 페이지 진입 → 넷퍼넬 키 반납
에이전트 설치
라이브러리 주입
의존성 추가
아래 코드를 복사하여 package.json에 의존성을 추가해주세요.
package.json
{
"dependencies": {
"netfunnel-rn-agent": "https://agent-lib.stclab.com/agents/static/rn/netfunnel-rn-agent-latest.tgz"
}
}
패키지 설치
프로젝트 루트 경로에서 아래의 명령어를 사용하여 패키지를 설치합니다.
npm install
에이전트 적용
초기화
Netfunnel.initialize 함수는 Netfunnel 서비스를 초기화하여 클라이언트와 서버 간의 통신 설정을 구성합니다.
이 함수는 애플리케이션 시작 시 필수적으로 호출되어야 하며, clientId와 같은 필수 파라미터를 포함한 설정 객체를 인자로 받아 Netfunnel의 동작을 정의합니다.
초기화가 완료되면, Netfunnel은 지정된 설정에 따라 동작하며, 이후 Netfunnel 관련 기능을 사용할 수 있습니다.
{{CLIENT_ID}}는 콘솔 화면 우측 상단의 프로필 아이콘을 클릭한 후,
'통합 자격 증명' 메뉴에서 확인하실 수 있습니다.
import Netfunnel from 'netfunnel-rn-agent';
Netfunnel.initialize({
clientId: '{{CLIENT_ID}}'
});
| 파라미터 | 설명 | 필수 | 조건/기본값 |
|---|---|---|---|
| clientId | 사용자 고유 식별자 | O | 빈 문자열 불가 |
| serverUrl | NetFUNNEL 서버 주소 | X | 없음 (기본 주소 사용) |
| errorUrl | NetFUNNEL 에러 페이지의 html 주소 | X | 없음 (기본 주소 사용) |
| networkTimeout | 네트워크 응답을 기다리는 최대 시간 | X | 기본: 3,000ms / 최대: 10,000ms / 최소: 100ms |
| retryCount | 네트워크 요청 실패 시 재시도 횟수 | X | 기본: 0회 / 최대: 10회 / 최소: 0회 |
| printLog | 디버그를 위한 로그 출력 여부 | X | 기본: false |
| errorBypass | 에러 발생 시 바이패스 여부 | X | 기본: false |
| useNetfunnelTemplate | 콘솔에서 커스텀한 NetFUNNEL 대기실 사용 여부 | X | 기본: true |
| userId | 블랙리스트, 화이트리스트 확인을 위한 end-user의 고유 식별자 | X | 기본: null |
| useNetworkRecoveryMode | 대기실이 뜬 상태에서 네트워크 연결 끊김 시, 대기실을 유지하며 networkTimeout 기준으로 재연결 시도 | X | 기본: false |
넷퍼넬 웹뷰 컴포넌트 설정
<Netfunnel.WebViewComponent />는 React Native 애플리케이션에서 Netfunnel의 대기실 기능을 웹뷰로 렌더링하는 컴포넌트입니다.
이 컴포넌트는 Netfunnel.initialize로 설정된 파라미터를 기반으로 동작하며, 사용자에게 대기실 UI를 표시하거나 Netfunnel 서버와의 상호작용을 처리합니다.
App 컴포넌트의 NavigationContainer 와 함께 배치하여, 앱의 네비게이션 흐름과 독립적으로 대기실 웹뷰를 렌더링할 수 있도록 합니다.
export default function App() {
return (
<View>
<NavigationContainer>
...
</NavigationContainer>
<Netfunnel.WebViewComponent />
</View>
);
}
기본 제어
기본 제어: 시작 함수
- 함수명:
nfStart - 설명: 대기를 적용하고 싶은 지점에서 함수를 호출하여 키를 발급하고 대기실을 노출시킵니다.
- 적용 위치: 페이지 진입이나 이벤트 시작 부분에 적용합니다.
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 기본제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 기본제어 세그먼트 키 | O |
| callback | Function | 대기실 이벤트 처리를 위한 사용자 정의 콜백 함수 | O |
Netfunnel.nfStart("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", function(response) {
// TODO: response에 따라 상황에 맞는 콜백 함수를 구현합니다.
nfCallback(response);
});
기본 제어: 종료 함수
- 함수명:
nfStop - 설명: 진입을 완료한 후 키 반납을 위해 사용합니다.
- 적용 위치: 시작 함수 종료 후 또는 진입 한 유저의 활동이 완료되는 지점에 적용합니다.
종료 함수를 실행하지 않으면 세그먼트의 타임아웃 설정에 따라 자동으로 반납 처리합니다.
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 기본제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 기본제어 세그먼트 키 | O |
Netfunnel.nfStop("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}");
구간 제어
구간제어란, 애플리케이션의 특정 구간에서 동시 접속자 수를 일정한 값으로 유지하도록 제어하는 기능입니다. 시작 함수 호출 시 키를 발급하고, 종료 함수를 호출하기 전까지는 유저가 활동 구간에 있는 것으로 판단하여 다음 대기자를 진입시키지 않습니다. 종료 함수를 호출하면 키를 반납하고 다음 대기자가 진입하게 됩니다.
구간 제어: 시작 함수
- 함수명:
nfStartSection - 설명: 대기를 적용하고 싶은 지점에서 함수를 호출하여 키를 발급하고 대기실을 노출시킵니다.
- 적용 위치: 페이지 진입이나 이벤트 시작 부분에 적용합니다.
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 구간제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 구간제어 세그먼트 키 | O |
| callback | Function | 대기실 이벤트 처리를 위한 사용자 정의 콜백 함수 | O |
Netfunnel.nfStartSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", function(response) {
// TODO: response에 따라 상황에 맞는 콜백 함수를 구현합니다.
nfCallback(response);
});
구간 제어: 종료 함수
- 함수명:
nfStopSection - 설명: 진입을 완료한 후 키 반납을 위해 사용합니다.
- 적용 위치: 진입한 유저의 활동 구간이 종료되는 지점에 적용합니다.
종료 함수를 실행하지 않으면 유저가 활동 구간에 계속 남아있는 것으로 간주되어 다음 대기자의 진입이 늦춰질 수 있습니다.
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 구간제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 구간제어 세그먼트 키 | O |
Netfunnel.nfStopSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}");
콜백 함수
기본제어와 구간제어 시작 함수의 두번째 파라미터인 콜백 함수에서 넷퍼넬 서버로부터의 응답을 받을 수 있습니다. 응답 결과에 따라 사용자는 다양한 처리 로직을 수행할 수 있습니다.
상태값 ‘Success’, ‘Error’, ‘NetworkError’에 대해서는 필수적으로 처리를 해야 합니다. 그 외의 상태값은 처리하지 않아도 서비스에 영향이 없습니다.
Success
| statusCode | message | 설명 |
|---|---|---|
| 200 | Success | 대기열을 정상적으로 통과하여 서비스에 진입 |
| 300 | Bypass | 구독/라이선스 만료 프로젝트/세그먼트 비활성화 data-nf-error-bypass=true로 설정 |
| 303 | Express | 진입 성공 시 동작 |
Error
| statusCode | message | 설명 |
|---|---|---|
| 500 | Server Error | 존재하지 않는 프로젝트/세그먼트 키 사용 대기 중 세그먼트 삭제 서버 에러로 인한 응답 누락 |
NetworkError
| statusCode | message | 설명 |
|---|---|---|
| 1001 | Network Not Connected | 네트워크 연결 차단 |
| 1002 | Network Timeout | 네트워크 지연 유효하지 않은 대기실 html 주소 넷퍼넬 서버 다운 |
Block
| statusCode | message | 설명 |
|---|---|---|
| 301 | Block | 세그먼트 차단 |
IpBlock
| statusCode | message | 설명 |
|---|---|---|
| 302 | Macro Block | 블랙리스트 BotManager Basic 활성화 |
Close
| statusCode | message | 설명 |
|---|---|---|
| 499 | Canceled Waiting Room | 기본 대기실의 취소 버튼 클릭 |
| 498 | Closed Blocking Room | 차단실의 닫기 버튼 클릭 |
| 497 | Closed Macro Blocking Room | 매크로 차단실의 닫기 버튼 클릭 |
| 496 | Closed PreWaiting Room | 사전 대기실의 닫기 버튼 클릭 |
| 495 | Closed PostWaiting Room | 사후 대기실의 닫기 버튼 클릭 |
function nfCallback(response) {
const { status, statusCode, message } = response;
switch(status) {
case 'Success':
// 진입 또는 우회 응답을 받은 경우로, 넷퍼넬을 적용하기 전의 기존 서비스 로직을 실행합니다.
// ex - 페이지 이동, 함수 실행, API 요청
break;
case 'Error':
// 시스템 에러가 발생한 경우로, 원활한 서비스 이용을 위해 일반적으로 Succss와 동일하게 기존 서비스 로직을 실행합니다.
// 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}`);
}
}