문제 해결
NetFUNNEL Flutter Agent 통합에 대한 일반적인 문제, 해결 방법 및 자주 묻는 질문입니다.
설치 문제
패키지 설치 실패
증상:
flutter pub get실패- 패키지를 찾을 수 없음
해결 방법:
- 네트워크 연결 확인: 인터넷 연결 상태 확인
- 패키지 경로 확인:
pubspec.yaml의 의존성 경로가 올바른지 확인 - tar.gz 파일 확인: tar.gz 파일이 올바른 위치에 있는지 확인
- 들여쓰기 확인:
pubspec.yaml파일의 들여쓰기가 올바른지 확인
초기화 실패
증상:
- 앱 시작 시 에러 발생
- NetFUNNEL이 초기화되지 않음
해결 방법:
- clientId 확인:
clientId가 올바르게 설정되었는지 확인 - 빈 문자열 확인:
clientId가 빈 문자열이 아닌지 확인 - 초기화 위치:
main.dart의main()함수 시작 부분에서 초기화하는지 확인 - async/await 확인:
main()함수가async로 선언되어 있고await를 사용하는지 확인
함수 호출 오류
"nfStart is not a function" 오류
증상:
NoSuchMethodError: The method 'nfStart' was called on null- 함수가 호출될 때 정의되지 않음
해결 방법:
- 초기화 확인:
Netfunnel.instance.initialize()가 먼저 호출되었는지 확인 - import 확인:
import 'package:netfunnel_flutter/netfunnel_flutter.dart'가 올바른지 확인 - 함수 사용법:
Netfunnel.instance.nfStart()형식으로 호출하는지 확인
콜백이 실행되지 않음
증상:
nfStart가 호출되었지만 콜백이 실행되지 않음- 응답을 받지 못함
해결 방법:
- 네트워크 확인: NetFUNNEL 서버에 대한 네트워크 요청 확인
- 콘솔 로그:
printLog: true로 설정하여 디버깅 로그 확인 - 세그먼트 상태: 세그먼트가 Block 상태가 아닌지 확인
- 진입 허용수: 진입 허용수가 진입을 허용하는지 확인
네트워크 및 연결 문제
네트워크 타임아웃 오류
증상:
onNetworkError상태 코드 1002- 요청이 타임아웃됨
해결 방법:
- 타임아웃 증가:
networkTimeout을 더 높은 값으로 설정 (최대 10000ms) - 재시도 구성:
retryCount증가 - 네트워크 복구:
useNetworkRecoveryMode: true활성화
await Netfunnel.instance.initialize(
clientId: 'your-client-id',
networkTimeout: 5000,
retryCount: 2,
useNetworkRecoveryMode: true,
);
네트워크 연결 오류
증상:
onNetworkError상태 코드 1001- 인터넷 연결 없음
해결 방법:
- 연결 확인: 인터넷 연결 상태 확인
- 방화벽: NetFUNNEL 도메인이 차단되지 않았는지 확인
- 프록시 설정: 필요한 경우 프록시 구성
- 오류 처리: 적절한 NetworkError 처리 구현
class NetfunnelHandler extends NetfunnelCallback {
@override
void onNetworkError(int statusCode, String message) {
// 사용자 친화적인 메시지 표시
showDialog(
context: context,
builder: (context) => AlertDialog(
title: Text('네트워크 연결 문제'),
content: Text('인터넷 연결을 확인해주세요.'),
),
);
// 선택적으로 재시도하거나 계속 진행
}
}
HTTP 통신 시 오류
증상:
- HTTP 통신 시 오류 발생
- HTTPS 통신은 정상 작동
해결 방법:
NetFUNNEL Flutter 에이전트는 기본적으로 HTTPS 통신을 권장합니다. HTTP 통신을 사용할 경우, 플랫폼에 따른 설정을 통해 HTTP 통신을 허용할 수 있습니다.
Android:
android/app/src/main/res/xml/network_security_config.xml 파일 생성:
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
<domain-config cleartextTrafficPermitted="true">
<domain includeSubdomains="true">{{DOMAIN_URL}}</domain>
</domain-config>
</network-security-config>
android/app/src/main/AndroidManifest.xml 설정 추가:
<application
android:networkSecurityConfig="@xml/network_security_config"
... >
</application>
iOS:
ios/Runner/Info.plist 설정 추가:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
대기실 문제
대기실이 표시되지 않음
증상:
- 대기실이 나타나지 않음
- 사용자가 직접 진행함
해결 방법:
- 진입 허용수: 테스트를 위해 0으로 설정
- 세그먼트 활성화: 세그먼트가 활성화되어 있는지 확인
- 템플릿 설정:
useNetfunnelTemplate: true확인 - 콜백 구현: 필수 콜백 함수(
onSuccess,onError,onNetworkError)가 구현되어 있는지 확인
대기실이 멈춤 (끝나지 않음)
증상:
- 대기실이 나타나지만 진입이 허용되지 않음
- 무한 대기
해결 방법:
- 진입 허용수: 진입 허용수 값 증가
- 세그먼트 상태: 세그먼트가 Block 상태인지 확인
- 네트워크 문제: 네트워크 연결 상태 확인
- 서버 상태: NetFUNNEL 서버 상태 확인
키 관리 문제
키가 반납되지 않음
증상:
- 다음 사용자가 무한정 대기함
- 대기열이 진행되지 않음
해결 방법:
- nfStop 호출: 항상
nfStop/nfStopSection호출 확인 - 오류 처리: 오류 시나리오에서도 키 반납
- 타임아웃 확인: 세그먼트 타임아웃 설정 확인
try {
await performAction();
await Netfunnel.instance.nfStop(
projectKey: projectKey,
segmentKey: segmentKey,
);
} catch (error) {
print('작업 실패: $error');
// 오류 발생 시에도 키 반납
await Netfunnel.instance.nfStop(
projectKey: projectKey,
segmentKey: segmentKey,
);
}
디버깅 팁
로그 확인
디버깅을 위해 printLog: true로 설정하여 로그를 확인할 수 있습니다:
await Netfunnel.instance.initialize(
clientId: 'your-client-id',
printLog: true, // 디버깅 로그 활성화
);
Flutter 콘솔에서 [NF4] prefix를 가진 로그를 확인하세요.
에이전트 버전 확인
에이전트의 버전을 확인하기 위해 getVersion() 함수를 사용할 수 있습니다:
String version = Netfunnel.instance.getVersion();
print('NetFUNNEL Agent 버전: $version');
일반적인 확인 사항
- 초기화 확인:
Netfunnel.instance.initialize()가 올바르게 호출되었는지 확인 - 콜백 구현: 필수 콜백 함수(
onSuccess,onError,onNetworkError)가 구현되어 있는지 확인 - 키 일치: 시작 및 종료 함수에서 동일한 키를 사용하는지 확인
- BuildContext:
nfStart/nfStartSection호출 시 유효한BuildContext를 전달하는지 확인