통합 가이드

1. 에이전트 소개

NetFUNNEL Flutter 에이전트는 NetFUNNEL 서버와 통신하는 전용 클라이언트입니다.

2. 에이전트 설치

2.1 최소 요구 사항

• Flutter 3.0.0 이상
• Dart 3.0.0 이상

2.2 패키지 추가

NetFUNNEL Flutter 에이전트는 tar.gz 패키지로 제공되며, pub.dev가 아닌 로컬 경로 의존성으로 추가합니다.

1. NetFUNNEL 콘솔의 에이전트 탭에서 Flutter 에이전트를 다운로드합니다.
2. tar.gz 파일을 프로젝트 루트 등 원하는 위치에 복사한 뒤 압축을 풉니다.
3. pubspec.yaml의 dependencies에 에이전트 경로를 추가합니다.

pubspec.yaml

dependencies:
  netfunnel_flutter:
    path: ./netfunnel_flutter-{VERSION}  # 압축을 푼 에이전트 경로

4. 프로젝트 루트에서 패키지를 설치합니다.

flutter pub get

주의

YAML은 들여쓰기로 구조를 구분합니다. netfunnel_flutter와 path의 들여쓰기가 맞지 않으면 패키지를 인식하지 못합니다.

2.3 Android 설정

NetFUNNEL 서버와 통신하기 위해 android/app/src/main/AndroidManifest.xml에 인터넷 권한을 추가합니다.

android/app/src/main/AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 인터넷 접속 권한 허용 -->
    <uses-permission android:name="android.permission.INTERNET" />
</manifest>

2.4 초기화

NetFUNNEL Flutter 에이전트는 앱 실행 시 한 번 초기화되어야 합니다. main()에서 runApp()을 호출하기 전에 초기화 함수를 실행합니다.

주의

초기화하지 않고 시작 함수를 호출하면 onError(500)가 호출됩니다. 반드시 앱 실행 시점에 초기화하세요.

lib/main.dart

import 'package:flutter/material.dart';
import 'package:netfunnel_flutter/netfunnel_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  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(const MyApp());
}

NetFUNNEL Flutter 에이전트는 다양한 부가 기능을 제공합니다. 부가 기능을 활성화하려면 초기화 함수에 설정값을 추가합니다. 모든 파라미터는 이름 지정 인자입니다.

파라미터	타입	설명	조건
clientId	String	클라이언트 고유 식별자	필수 · 빈 문자열 불가
serverUrl	String	NetFUNNEL 서버 주소	기본: 기본 주소 사용
errorUrl	String	NetFUNNEL 에러 페이지 HTML 주소	기본: 기본 주소 사용
networkTimeout	int	네트워크 응답 최대 대기 시간	기본 3,000ms · 최대 10,000ms · 최소 100ms
retryCount	int	네트워크 재시도 횟수	기본 0 · 최대 10 · 최소 0
printLog	bool	디버그 로그 출력	기본: false
errorBypass	bool	onError·onNetworkError 대신 onSuccess 호출	기본: false
useNetfunnelTemplate	bool	NetFUNNEL 대기실 사용 (false면 커스텀 대기실)	기본: true
userId	String	반복 요청 차단의 ID 기준 차단·허용에 사용할 사용자 ID	기본: null
useNetworkRecoveryMode	bool	네트워크 에러 시 대기실 유지 및 회복	기본: false
profile	String	서비스 환경 프로필 (prod_tokyo, prod_us_east)	기본: prod_tokyo

3. 에이전트 적용

Flutter 에이전트는 코드 기반 적용을 지원합니다. 대기열을 적용할 화면에서 시작 함수를 호출하고, 진입이 완료된 시점에 종료 함수를 호출합니다. 대기열 적용 지점을 바꿀 때마다 앱 배포가 필요하지만, 트래픽이 발생하기 전에 대기실을 노출하므로 트래픽을 사전에 효과적으로 제어할 수 있습니다.

3.1 기본 제어

시작 함수

대기를 적용하고 싶은 지점에서 함수를 호출하여 키를 발급하고 대기실을 노출시킵니다. 화면 진입이나 이벤트 시작 부분에 적용합니다.

파라미터	타입	설명	필수
projectKey	String	NetFUNNEL 콘솔의 프로젝트 키	O
segmentKey	String	NetFUNNEL 콘솔의 세그먼트 키	O
callback	NetfunnelCallback	대기실 이벤트 처리를 위한 콜백 객체	O
context	BuildContext	대기실을 띄울 현재 화면의 context	O

await Netfunnel.instance.nfStart(
  projectKey: '{PROJECT_KEY}',
  segmentKey: '{SEGMENT_KEY}',
  callback: StartCallback(),
  context: context,
);

종료 함수

진입을 완료한 후 키 반납을 위해 사용합니다. 진입 성공 후 서비스 로직이 끝나는 지점에 적용합니다.

파라미터	타입	설명	필수
projectKey	String	NetFUNNEL 콘솔의 프로젝트 키	O
segmentKey	String	NetFUNNEL 콘솔의 세그먼트 키	O

await Netfunnel.instance.nfStop(
  projectKey: '{PROJECT_KEY}',
  segmentKey: '{SEGMENT_KEY}',
);

3.2 구간 제어

구간 제어란, 앱의 특정 구간에서 동시 접속자 수를 일정하게 유지하도록 제어하는 기능입니다. 시작 함수 호출 시 키를 발급하고, 종료 함수를 호출하기 전까지는 유저가 활동 구간에 있는 것으로 판단하여 다음 대기자를 진입시키지 않습니다. 종료 함수를 호출하면 키를 반납하고 다음 대기자가 진입합니다. (예: 상품 페이지부터 결제까지, 로그인부터 로그아웃까지)

시작 함수

구간이 시작되는 지점에서 호출합니다. 파라미터는 기본 제어의 시작 함수와 같습니다.

await Netfunnel.instance.nfStartSection(
  projectKey: '{PROJECT_KEY}',
  segmentKey: '{SEGMENT_KEY}',
  callback: StartCallback(),
  context: context,
);

종료 함수

진입한 유저의 활동 구간이 종료되는 지점에서 호출합니다. 파라미터는 기본 제어의 종료 함수와 같습니다.

await Netfunnel.instance.nfStopSection(
  projectKey: '{PROJECT_KEY}',
  segmentKey: '{SEGMENT_KEY}',
);

3.3 콜백 처리

시작 함수에 전달한 NetfunnelCallback으로 넷퍼넬 서버의 응답을 받습니다. NetfunnelCallback을 상속한 클래스를 만들어 응답 결과에 따른 처리 로직을 구현합니다.

참고

onSuccess, onError, onNetworkError는 반드시 구현해야 합니다. 그 외 콜백은 구현하지 않아도 서비스에 영향이 없습니다.

콜백	statusCode	설명
onSuccess	200	대기열을 정상적으로 통과하여 서비스에 진입
onSuccess	300	구독·라이선스 만료 · 프로젝트·세그먼트 비활성화 · errorBypass=true 설정
onSuccess	303	화이트리스트 IP·ID 요청 (우회)
onError	500	초기화 없이 시작 함수 호출 · 존재하지 않는 프로젝트·세그먼트 키 사용 · 대기 중 세그먼트 삭제 · 서버 응답 누락
onNetworkError	1001	네트워크 연결 차단 (Wi-Fi·셀룰러 차단)
onNetworkError	1002	네트워크 타임아웃 · 유효하지 않은 대기실 HTML 주소 · 넷퍼넬 서버 다운
onBlock	301	세그먼트 차단
onBlock	302	블랙리스트 · BotManager Basic 활성화
onClose	499	기본 대기실의 취소 버튼 클릭
onClose	498	차단실의 닫기 버튼 클릭
onClose	497	매크로 차단실의 닫기 버튼 클릭
onClose	496	사전 대기실의 닫기 버튼 클릭
onClose	495	사후 대기실의 닫기 버튼 클릭
onContinue	201	useNetfunnelTemplate=false로 대기 중 (커스텀 대기실)

StartCallback 예시

import 'package:netfunnel_flutter/netfunnel_flutter.dart';

class StartCallback extends NetfunnelCallback {
  @override
  void onSuccess(int statusCode, String message) {
    // 진입 또는 우회 응답: 넷퍼넬 적용 이전의 원래 서비스 로직 실행
    // 예) 화면 이동, 함수 실행, API 요청
  }

  @override
  void onError(int statusCode, String message) {
    // 시스템 에러: 원활한 서비스 이용을 위해 원래 서비스 로직 실행
  }

  @override
  void onNetworkError(int statusCode, String message) {
    // 네트워크 에러: 원래 로직 실행 또는 안내 후 대기열 재진입
  }

  @override
  void onBlock(int statusCode, String message) {
    // 진입 차단: 차단 안내 또는 무동작
  }

  @override
  void onClose(int statusCode, String message) {
    // 대기실 닫기·취소: 취소 안내 또는 무동작
  }

  @override
  void onContinue(int statusCode, String message, int aheadWait,
      int behindWait, String waitTime, int progressRate) {
    // 커스텀 대기실 사용 시: 대기 정보로 UI 갱신
  }
}