설치 및 초기화
이 가이드는 NetFUNNEL React Native 에이전트의 설치 및 초기화 과정을 설명합니다.
1단계: 패키지 설치
의존성 추가
package.json에 다음 의존성을 추가합니다:
{
"dependencies": {
"netfunnel-rn-agent": "https://agent-lib.stclab.com/agents/static/rn/netfunnel-rn-agent-latest.tgz"
}
}
패키지 설치
프로젝트 루트 경로에서 다음 명령어를 실행합니다:
npm install
2단계: Client ID 가져오기
- NetFUNNEL 콘솔로 이동
- 우측 상단의 프로필 아이콘 클릭
통합 자격 증명(Integration Credentials) 메뉴 선택Client ID복사
Client ID 확인 위치
콘솔 화면 우측 상단의 프로필 아이콘을 클릭한 후, 통합 자격 증명 메뉴에서 확인할 수 있습니다.
3단계: 에이전트 초기화
NetFUNNEL React Native 에이전트는 앱 실행과 동시에 초기화되어야 합니다.
App.js 또는 App.tsx의 main() 함수 시작 시점에서 초기화 작업을 수행합니다:
import Netfunnel from 'netfunnel-rn-agent';
Netfunnel.initialize({
clientId: '{{CLIENT_ID}}', // 2단계에서 가져온 Client ID
serverUrl: '{{SERVER_URL}}', // 선택사항
errorUrl: '{{ERROR_URL}}', // 선택사항
networkTimeout: 3000,
retryCount: 0,
printLog: false,
errorBypass: false,
useNetfunnelTemplate: true,
userId: '{{USER_ID}}', // 선택사항
useNetworkRecoveryMode: true
});
초기화 매개변수
| 매개변수 | 타입 | 설명 | 조건 |
|---|---|---|---|
clientId | String | 사용자 고유 식별자 | 빈 문자열 불가 |
serverUrl | String | NetFUNNEL 서버 주소 | 없음 (기본 주소 사용) |
errorUrl | String | NetFUNNEL 에러 페이지의 html 주소 | 없음 (기본 주소 사용) |
networkTimeout | int | 네트워크 응답을 기다리는 최대 시간 | 기본 (ms): 3,000 최대 (ms): 10,000 최소 (ms): 100 |
retryCount | int | 네트워크 요청 실패 시 재시도 횟수 | 기본 (time): 0 최대 (time): 10 최소 (time): 0 |
printLog | bool | 디버그를 위한 로그 출력 여부 | 기본: false |
errorBypass | bool | 에러 발생 시 바이패스 여부 | 기본: false |
useNetfunnelTemplate | bool | 콘솔에서 커스텀한 NetFUNNEL 대기실 사용 여부 | 기본: true |
userId | String | 블랙리스트, 화이트리스트를 확인을 위한 end-user의 고유 식별자 | 기본: null |
useNetworkRecoveryMode | bool | 대기실이 뜬 상태에서 네트워크 연결 끊김 시 대기실을 유지하고 networkTimeout 기준으로 계속하여 재연결을 시도하여 대기실을 유지시키는 기능 | 기본: false |
초기화 설정 상세 정보
모든 초기화 매개변수에 대한 자세한 정보는 초기화 설정 문서를 참조하세요.
4단계: WebView 컴포넌트 추가
<Netfunnel.WebViewComponent />는 React Native 애플리케이션에서 Netfunnel의 대기실 기능을 웹뷰로 렌더링하는 컴포넌트입니다.
이 컴포넌트는 Netfunnel.initialize로 설정된 파라미터를 기반으로 동작하며, 사용자에게 대기실 UI를 표시하거나 Netfunnel 서버와의 상호작용을 처리합니다.
App 컴포넌트의 NavigationContainer와 함께 배치하여, 앱의 네비게이션 흐름과 독립적으로 대기실 웹뷰를 렌더링할 수 있도록 합니다:
import { View } from 'react-native';
import { NavigationContainer } from '@react-navigation/native';
import Netfunnel from 'netfunnel-rn-agent';
export default function App() {
return (
<View>
<NavigationContainer>
{/* Your app navigation */}
</NavigationContainer>
<Netfunnel.WebViewComponent />
</View>
);
}
5단계: 설치 확인
에이전트가 올바르게 설치되었는지 확인하려면 다음을 확인하세요:
- 초기화 성공: 앱 시작 시 에러가 발생하지 않아야 합니다
- WebView 컴포넌트:
<Netfunnel.WebViewComponent />가 정상적으로 렌더링되어야 합니다 - 로그 확인:
printLog: true로 설정한 경우, 콘솔에서[NF4]prefix를 가진 로그를 확인할 수 있습니다
문제 해결
패키지 설치 실패:
- 네트워크 연결 확인
package.json의 의존성 경로 확인
초기화 실패:
clientId가 올바르게 설정되었는지 확인- 빈 문자열이 아닌지 확인
WebView 컴포넌트가 표시되지 않음:
<Netfunnel.WebViewComponent />가 올바른 위치에 추가되었는지 확인- NavigationContainer와 함께 배치되었는지 확인