설치 및 초기화
이 가이드는 NetFUNNEL Flutter 에이전트의 설치 및 초기화 과정을 설명합니다.
1단계: 패키지 설치
의존성 추가
NetFUNNEL Flutter 에이전트는 tar.gz 패키지 파일로 제공됩니다. 공개 저장소(pub.dev)를 사용하지 않고, 제공받은 압축 파일을 프로젝트에 직접 추가하여 설치해야 합니다.
tar.gz 파일을 프로젝트 루트 또는 원하는 위치에 복사한 뒤, pubspec.yaml에 의존성을 추가합니다:
dependencies:
netfunnel_flutter:
path: ./netfunnel_flutter-{{latest}} # tar.gz 파일을 복사한 경로
들여쓰기 주의
pubspec.yaml 파일은 들여쓰기에 따라 계층 구조로 인식되므로, 들여쓰기에 주의가 필요합니다.
패키지 설치
프로젝트 루트 경로에서 다음 명령어를 실행합니다:
flutter pub get
2단계: 네트워크 권한 설정
Android
Android의 경우, NetFUNNEL 서버와 통신하기 위해 인터넷 사용 권한을 추가해야 합니다.
android/app/src/main/AndroidManifest.xml 파일에 다음 권한을 추가합니다:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<!-- 인터넷 권한 설정 -->
<uses-permission android:name="android.permission.INTERNET" />
</manifest>
iOS
iOS는 기본적으로 인터넷 권한이 활성화되어 있습니다. 추가 설정이 필요하지 않습니다.
3단계: Client ID 가져오기
- NetFUNNEL 콘솔로 이동
- 우측 상단의 프로필 아이콘 클릭
통합 자격 증명(Integration Credentials) 메뉴 선택Client ID복사
Client ID 확인 위치
콘솔 화면 우측 상단의 프로필 아이콘을 클릭한 후, 통합 자격 증명 메뉴에서 확인할 수 있습니다.
4단계: 에이전트 초기화
NetFUNNEL Flutter 에이전트는 앱 실행과 동시에 초기화되어야 합니다.
main.dart의 main() 함수 시작 시점에서 초기화 작업을 수행합니다:
import 'package:netfunnel_flutter/netfunnel_flutter.dart';
void main() async {
// NetFUNNEL 에이전트 초기화
await Netfunnel.instance.initialize(
clientId: '{{CLIENT_ID}}', // 3단계에서 가져온 Client ID
serverUrl: '{{SERVER_URL}}', // 선택사항
errorUrl: '{{ERROR_URL}}', // 선택사항
networkTimeout: 3000,
retryCount: 0,
printLog: false,
errorBypass: false,
useNetfunnelTemplate: true,
userId: '{{USER_ID}}', // 선택사항
useNetworkRecoveryMode: true,
profile: 'prod_tokyo',
);
runApp(MyApp());
}
초기화 매개변수
| 매개변수 | 타입 | 설명 | 조건 |
|---|---|---|---|
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 | 네트워크 연결 끊김 시 대기실을 유지하고 재연결을 시도하는 기능 사용 여부 | 기본: false |
profile | String | 사용자 환경 설정 (prod_tokyo, prod_us_east) | 기본: prod_tokyo |
초기화 설정 상세 정보
모든 초기화 매개변수에 대한 자세한 정보는 초기화 설정 문서를 참조하세요.
5단계: 설치 확인
에이전트가 올바르게 설치되었는지 확인하려면 다음을 확인하세요:
- 초기화 성공: 앱 시작 시 에러가 발생하지 않아야 합니다
- 로그 확인:
printLog: true로 설정한 경우, Flutter 콘솔에서[NF4]prefix를 가진 로그를 확인할 수 있습니다
문제 해결
패키지 설치 실패:
- 네트워크 연결 확인
pubspec.yaml의 의존성 경로 확인- tar.gz 파일이 올바른 위치에 있는지 확인
초기화 실패:
clientId가 올바르게 설정되었는지 확인- 빈 문자열이 아닌지 확인