Flutter Agent
개요
NetFUNNEL Flutter 에이전트는 NetFUNNEL 서버와 통신하는 전용 클라이언트입니다.
최소 요구사항
- Flutter 3.0.0 이상
- Dart 3.0.0 이상
에이전트 동작 흐름
대기 전
- 대기 전, 설정 정보를 초기화합니다. 이 과정은 NetFUNNEL 서버로부터 설정 정보를 Fetch하고 해당 정보들을 기반으로 객체들을 초기화하는 과정입니다.
- “초기화 함수”를 사용하여 NetFUNNEL의 설정 정보를 초기화하세요.
대기 중
- 가상 대기실을 노출하여 트래픽 대기를 적용하고 싶은 화면(Screen)에서 대기시키는 과정입니다.
- “대기 시작 함수”를 사용하여 가상 대기실을 적용하세요.
대기 후
- 대기가 종료된 이후 상황에 대한 처리 과정입니다. end-user의 대기가 종료되는 상황은 다음과 같습니다.
- 대기 마친 후, 진입 성공
- 대기 도중, 서버 에러 혹은 네트워크 에러 상황으로 인해 진입 실패
- 대기 도중, end-user의 대기 취소
- “콜백 함수”와 “대기 종료 함수”를 사용하여 대기 종료 후 로직을 구현하세요.
에이전트 설치
NetFUNNEL Flutter 에이전트는 tar.gz 패키지 파일로 제공됩니다.
공개 저장소(pub.dev)를 사용하지 않고, 제공받은 압축 파일을 프로젝트에 직접 추가하여 설치해야 합니다.
에이전트 설치
tar.gz 파일을 프로젝트 루트 또는 원하는 위치에 복사한 뒤, Flutter 프로젝트의 pubspec.yaml에 의존성을 추가하여 패키지를 설치합니다.
경고
pubspec.yaml 파일은 들여쓰기에 따라 계층 구조로 인식되므로, 들여쓰기에 주의가 필요합니다.
pubspec.yaml
dependencies:
netfunnel_flutter:
path: ./netfunnel_flutter-{{latest}} # tar.gz 파일을 복사한 경로
Terminal
flutter pub get
네트워크 권한 설정
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>
에이전트 초기화
NetFUNNEL Flutter 에이전트는 앱 실행과 동시에 초기화되어야 합니다.
정보
main.dart의 main() 함수 시작 시점에서 초기화 작업을 수행합니다.
import 'package:netfunnel_flutter/netfunnel_flutter.dart';
void main() async {
// NetFUNNEL 에이전트 초기화
await Netfunnel.instance.initialize(
clientId: '{{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 | 사용자 고유 식별자 | O | 빈 문자열 불가 |
| serverUrl | String | NetFUNNEL 서버 주소 | X | 없음 (기본 주소 사용) |
| errorUrl | String | NetFUNNEL 에러 페이지의 html 주소 | X | 없음 (기본 주소 사용) |
| networkTimeout | int | 네트워크 응답을 기다리는 최대 시간 | X | 기본: 3,000ms 최대: 10,000ms 최소: 100ms |
| retryCount | int | 네트워크 요청 실패 시 재시도 횟수 | X | 기본: 0회 최대: 10회 최소: 0회 |
| printLog | bool | 디버그를 위한 로그 출력 여부 | X | 기본: false |
| errorBypass | bool | 에러 발생 시 바이패스 여부 | X | 기본: false |
| useNetfunnelTemplate | bool | 콘솔에서 커스텀한 NetFUNNEL 대기실 사용 여부 | X | 기본: true |
| userId | String | 블랙리스트, 화이트리스트 확인을 위한 end-user의 고유 식별자 | X | 기본: null |
| useNetworkRecoveryMode | bool | 네트워크 연결 끊김 시 대기실을 유지하고 재연결 시도 기능 사용 여부 | X | 기본: false |
| profile | String | 사용자 환경 설정 (prod_tokyo, prod_us_east) | X | 기본: prod_tokyo |
에이전트 적용
NetFUNNEL Flutter 에이전트에서 제공하는 함수를 통해 특정 화면에 대기실을 적용할 수 있습니다.
정보
시작 함수와 종료 함수에 사용하는 프로젝트 키와 세그먼트 키는 콘솔의 프로젝트 탭에서 확인 가능합니다.
콜백 함수
NetFUNNEL Flutter 에이전트를 사용하기 위해서는 시작 함수와 종료 함수에 콜백 함수를 반드시 주입해야 합니다.
대기실은 다양한 상황(대기 성공, 취소, 차단, 에러, 네트워크 오류 등)에 따라 종료될 수 있으며, 각 상황에 대한 처리 시나리오는 콜백 함수를 통해 구현할 수 있습니다.
abstract class: NetfunnelCallback
| 콜백 함수 | 필수 구현 여부 |
|---|---|
| onSuccess | 필수 |
| onError | 필수 |
| onNetworkError | 필수 |
| onBlock | 선택 |
| onClose | 선택 |
| onContinue | 선택 |
| 콜백 함수 | 상태 코드 | 시나리오 |
|---|---|---|
| onSuccess | 200 | 200: 대기열을 정상 통과하여 서비스 이용이 허용 200: 대기열을 정상 통과하여 서비스 이용이 허용 200: 대기열을 정상 통과하여 서비스 이용이 허용 |
| onSuccess | 300 | 300: 구독이나 라이센스 만료 300: 콘솔의 프로젝트/세그먼트 비활성화 300: 에이전트의 errorBypass=true 설정 및 에러 발생 시 |
| onSuccess | 303 | 303: 콘솔의 화이트리스트에 등록된 IP 혹은 ID로 요청한 경우 (관리자 전용 바이패스) 303: 콘솔의 화이트리스트에 등록된 IP 혹은 ID로 요청한 경우 (관리자 전용 바이패스) 303: 콘솔의 화이트리스트에 등록된 IP 혹은 ID로 요청한 경우 (관리자 전용 바이패스) |
| onError | 500 | 500: 에이전트의 초기화 함수 없이 시작 함수 호출 500: 에이전트의 시작 함수에 존재하지 않는 프로젝트/세그먼트 키 사용 500: 콘솔의 세그먼트 삭제 500: 서버 에러로 인해 응답이 일부 누락된 경우 500: 에이전트의 초기화 함수 없이 시작 함수 호출 |
| onNetworkError | 1001 | 1001: 네트워크 연결 차단 (와이파이, 셀룰러 데이터 차단) 1001: 네트워크 연결 차단 (와이파이, 셀룰러 데이터 차단) 1001: 네트워크 연결 차단 (와이파이, 셀룰러 데이터 차단) |
| onNetworkError | 1002 | 1002: 네트워크 타임아웃 1002: 서버 에러로 인해 유효하지 않은 HTML URL 받은 경우 1002: 서버 다운으로 인해 응답받지 못할 경우 (502 등) |
| onBlock | 301 | 301: 콘솔의 세그먼트 차단 (선의적 진입 차단) 301: 콘솔의 세그먼트 차단 (선의적 진입 차단) 301: 콘솔의 세그먼트 차단 (선의적 진입 차단) |
| onBlock | 302 | 302: 콘솔의 블랙리스트에 등록된 IP 혹은 ID로 요청한 경우 (관리자 전용 차단) 302: 콘솔의 BotManager Basic 활성화 (악의적 진입 차단) 302: 콘솔의 블랙리스트에 등록된 IP 혹은 ID로 요청한 경우 (관리자 전용 차단) |
| onClose | 495 | 495: 사후 대기실의 닫기 버튼 클릭 495: 사후 대기실의 닫기 버튼 클릭 495: 사후 대기실의 닫기 버튼 클릭 |
| onClose | 496 | 496: 사전 대기실의 닫기 버튼 클릭 496: 사전 대기실의 닫기 버튼 클릭 496: 사전 대기실의 닫기 버튼 클릭 |
| onClose | 497 | 497: 매크로 차단실의 닫기 버튼 클릭 497: 매크로 차단실의 닫기 버튼 클릭 497: 매크로 차단실의 닫기 버튼 클릭 |
| onClose | 498 | 498: 차단실의 닫기 버튼 클릭 498: 차단실의 닫기 버튼 클릭 498: 차단실의 닫기 버튼 클릭 |
| onClose | 499 | 499: 기본 대기실의 취소 버튼 클릭 499: 기본 대기실의 취소 버튼 클릭 499: 기본 대기실의 취소 버튼 클릭 |
| onContinue | 201 | 201: 에이전트의 useNetfunnelTemplate=false 설정 및 기본 대기 시 201: 에이전트의 useNetfunnelTemplate=false 설정 및 기본 대기 시 201: 에이전트의 useNetfunnelTemplate=false 설정 및 기본 대기 시 |
import 'package:netfunnel_flutter/netfunnel_flutter.dart';
class NetfunnelHandler extends NetfunnelCallback {
static const String _tag = "[APP]";
@override
void onSuccess(int statusCode, String message) {
print('$_tag onSuccess: $statusCode $message');
/// 대기열 통과 시 처리할 로직
/// ex - 서비스 화면 진입 처리
}
@override
void onError(int statusCode, String message) {
print('$_tag onError: $statusCode $message');
/// 에러 발생 시 처리할 로직
/// ex - 사용자에게 오류 메시지 표시 또는 바이패스
}
@override
void onNetworkError(int statusCode, String message) {
print('$_tag onNetworkError: $statusCode $message');
/// 네트워크 에러 발생 시 처리할 로직
/// ex - 네트워크 재연결 안내 또는 재시도 화면으로 이동
}
@override
void onBlock(int statusCode, String message) {
print('$_tag onBlock: $statusCode $message');
/// 사용자 진입 차단 시 처리할 로직
/// ex - 접근 제한 메시지 표시
}
@override
void onClose(int statusCode, String message) {
print('$_tag onClose: $statusCode $message');
/// 사용자가 대기를 취소한 경우 처리할 로직
/// ex - 종료 안내 메시지 표시
}
@override
void onContinue(int statusCode, String message, int aheadWait, int behindWait, String waitTime, int progressRate) {
print('$_tag onContinue: $statusCode $message');
/// 대기 진행 중 UI 업데이트 로직 (자체 커스텀 대기실 사용 시에만 해당)
/// ex - 실시간 대기 정보를 커스텀 대기 화면에 업데이트
}
}
기본 제어
시작 함수
특정 화면(Widget 혹은 Page)에서 대기실을 적용시키기 위해서는 "대기 시작 함수"를 사용하여 가상 대기실을 노출시킬 수 있습니다. 기본 제어는 end-user가 특정 화면에 진입할 때 대기를 적용하여 서버 부하를 조절하고, end-user 경험을 관리하는 데 유용합니다.
await Netfunnel.instance.nfStart(
projectKey: '{{PROJECT_KEY}}',
segmentKey: '{{SEGMENT_KEY}}',
callback: callback,
context: context,
);
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 기본제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 기본제어 세그먼트 키 | O |
| callback | Function | 대기실 이벤트 처리를 위한 사용자 정의 콜백 함수 | O |
| context | BuildContext | 대기실을 적용시키는 화면의 BuildContext | O |
종료 함수
기본 제어의 대기를 성공적으로 마치는 경우, 아래와 같은 2가지 상황을 구현해야 합니다.
- 대기를 마치고 서비스로 진입하는 코드 (타겟 페이지로 진입하는 코드)
- 비즈니스 로직을 마치고 “대기 종료 함수”를 호출하여 서비스 진입 키를 NetFUNNEL 서버에 반납하는 코드
await Netfunnel.instance.nfStop(
projectKey: '{{PROJECT_KEY}}',
segmentKey: '{{SEGMENT_KEY}}',
);
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 기본제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 기본제어 세그먼트 키 | O |
구간 제어
구간 제어는 특정 페이지의 진입과 종료 사이에 대기 상태를 적용하는 방법입니다. 구간 제어를 통해 사용자는 페이지의 특정 구간에서 원활한 흐름을 유지할 수 있습니다.
- 이벤트 페이지에 진입한 후 상품을 구매하고, 결제 완료 버튼을 클릭한 경우
- end-user의 로그인 이후 로그아웃할 때까지의 주기
구간 제어를 시작하기 위해서는, “구간 시작 함수”를 사용하여 특정 제어 구간의 시작을 정의해야 합니다. 이에 따라 특정 구간의 흐름에서 대기 상태를 유지하도록 설정할 수 있습니다.
await Netfunnel.instance.nfStartSection(
projectKey: '{{PROJECT_KEY}}',
segmentKey: '{{SEGMENT_KEY}}',
callback: callback,
context: context,
);
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 구간제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 구간제어 세그먼트 키 | O |
| callback | Function | 대기실 이벤트 처리를 위한 사용자 정의 콜백 함수 | O |
| context | BuildContext | 대기실을 적용시키는 화면의 BuildContext | O |
종료 함수
구간 제어의 대기를 성공적으로 마치는 경우, 아래와 같은 상황을 구현할 수 있습니다.
- 대기를 마치고 서비스로 진입하는 코드 (타켓 페이지로 진입하는 코드)
구간 제어를 종료하기 위해서는, “구간 종료 함수”를 사용하여 특정 구간의 끝을 정의해야 합니다. 이에 따라 end-user의 구간 제어를 종료하고 다음 end-user가 진입할 수 있도록 설정할 수 있습니다.
await Netfunnel.instance.nfStopSection(
projectKey: '{{PROJECT_KEY}}',
segmentKey: '{{SEGMENT_KEY}}',
);
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 구간제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 구간제어 세그먼트 키 | O |