버전: 4.6.1-saas

API 참조

NetFUNNEL Flutter Agent 함수, 콜백 및 응답 형식에 대한 완전한 참조입니다.

기본 제어 함수

기본 제어는 서비스에 대한 진입 속도를 제한합니다. 시작 함수가 호출되면 키가 발급되고 대기실이 나타납니다. 종료 함수가 호출되면 키가 반납됩니다.

Netfunnel.instance.nfStart

목적: 작업 시작 시 키를 발급하고 대기실을 표시합니다.

함수 시그니처:

Future<void> nfStart({
  required String projectKey,
  required String segmentKey,
  required NetfunnelCallback callback,
  required BuildContext context,
})

매개변수:

매개변수	유형	설명
`projectKey`	String	콘솔의 기본 제어 프로젝트 키
`segmentKey`	String	콘솔의 기본 제어 세그먼트 키
`callback`	NetfunnelCallback	대기실 이벤트 처리를 위한 사용자 정의 콜백 함수
`context`	BuildContext	대기실을 적용시키는 화면의 BuildContext

반환값: Future<void>

예제:

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

콜백 처리: 자세한 응답 처리 내용은 콜백 함수 섹션을 참조하세요.

Netfunnel.instance.nfStop

목적: 진입이 완료된 후 키를 반환합니다.

함수 시그니처:

Future<void> nfStop({
  required String projectKey,
  required String segmentKey,
})

매개변수:

매개변수	유형	설명
`projectKey`	String	콘솔의 기본 제어 프로젝트 키
`segmentKey`	String	콘솔의 기본 제어 세그먼트 키

반환값: Future<void>

예제:

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

자동 반납 타임아웃

종료 함수를 실행하지 않으면 세그먼트 타임아웃 설정에 따라 키가 자동으로 반납됩니다 (기본 타임아웃: 20초).

구간 제어 함수

구간 제어는 특정 애플리케이션 구간 내의 동시 사용자 수를 고정된 값으로 유지합니다. 시작 함수가 호출되면 키가 발급됩니다. 종료 함수가 호출될 때까지 사용자는 활성 구간에 있는 것으로 간주되며, 대기열의 다음 사용자는 허용되지 않습니다.

Netfunnel.instance.nfStartSection

목적: 구간 제어를 위한 키를 발급하고 대기실을 표시합니다.

함수 시그니처:

Future<void> nfStartSection({
  required String projectKey,
  required String segmentKey,
  required NetfunnelCallback callback,
  required BuildContext context,
})

매개변수:

매개변수	유형	설명
`projectKey`	String	콘솔의 구간 제어 프로젝트 키
`segmentKey`	String	콘솔의 구간 제어 세그먼트 키
`callback`	NetfunnelCallback	대기실 이벤트 처리를 위한 사용자 정의 콜백 함수
`context`	BuildContext	대기실을 적용시키는 화면의 BuildContext

반환값: Future<void>

예제:

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

콜백 처리: 자세한 응답 처리 내용은 콜백 함수 섹션을 참조하세요.

Netfunnel.instance.nfStopSection

목적: 사용자가 활성 구간을 종료할 때 키를 반환합니다.

함수 시그니처:

Future<void> nfStopSection({
  required String projectKey,
  required String segmentKey,
})

매개변수:

매개변수	유형	설명
`projectKey`	String	콘솔의 구간 제어 프로젝트 키
`segmentKey`	String	콘솔의 구간 제어 세그먼트 키

반환값: Future<void>

예제:

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

구간 제어 동작

중지 함수를 실행하지 않으면 사용자는 활성 구간에 남아있는 것으로 간주되며, 다음 사용자의 허용이 지연될 수 있습니다.

콜백 함수

NetFUNNEL Flutter 에이전트를 사용하기 위해서는 시작 함수와 종료 함수에 콜백 함수를 반드시 주입해야 합니다.

대기실은 다양한 상황(대기 성공, 취소, 차단, 에러, 네트워크 오류 등)에 따라 종료될 수 있으며, 각 상황에 대한 처리 시나리오는 콜백 함수를 통해 구현할 수 있습니다.

필수 구현 함수

다음 세 가지 함수를 반드시 구현해야 합니다:

onSuccess: 진입 허용 또는 우회 모드
onError: 시스템 오류 발생
onNetworkError: 네트워크 연결 문제

선택 구현 함수

다음 함수들은 선택적으로 구현할 수 있습니다:

onBlock: 사용자 진입 차단
onClose: 사용자가 대기를 취소
onContinue: 대기 진행 중 UI 업데이트 (자체 커스텀 대기실 사용 시에만 해당)

샘플 콜백 구현

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 - 페이지 이동, 함수 실행, API 요청
  }

  @override
  void onError(int statusCode, String message) {
    print('$_tag onError: $statusCode $message');
    // 시스템 에러가 발생한 경우로, 원활한 서비스 이용을 위해 일반적으로 onSuccess와 동일하게 기존 서비스 로직을 실행합니다.
    // ex - 페이지 이동, 함수 실행, API 요청
  }

  @override
  void onNetworkError(int statusCode, String message) {
    print('$_tag onNetworkError: $statusCode $message');
    // 네트워크 에러가 발생한 경우로, 기존 서비스 로직을 실행하거나 알림 후 다시 대기열에 진입하도록 합니다.
    // ex - 페이지 이동, 함수 실행, API 요청, modal("네트워크가 불안정합니다. 다시시도 하시겠습니까? Y/N");
  }

  @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 - alert("대기를 취소하였습니다.");
  }

  @override
  void onContinue(int statusCode, String message, int aheadWait, int behindWait, String waitTime, int progressRate) {
    print('$_tag onContinue: $statusCode $message');
    // 대기 진행 중 UI 업데이트 로직 (자체 커스텀 대기실 사용 시에만 해당)
    // ex - 실시간 대기 정보를 커스텀 대기 화면에 업데이트
  }
}

상태 코드 참조

가능한 모든 상태 코드와 그 의미에 대한 완전한 참조입니다.

콜백 함수	statusCode	설명
onSuccess	200	대기열을 정상 통과하여 서비스 이용이 허용
	300	구독이나 라이센스 만료 콘솔의 프로젝트/세그먼트 비활성화 에이전트의 errorBypass=true 설정 및 에러 발생 시
	303	콘솔의 화이트리스트에 등록된 IP 혹은 ID로 요청한 경우 (관리자 전용 바이패스)
onError	500	에이전트의 초기화 함수 없이 시작 함수 호출 에이전트의 시작 함수에 존재하지 않는 프로젝트/세그먼트 키 사용 콘솔의 세그먼트 삭제 서버 에러로 인해 응답이 일부 누락된 경우
onNetworkError	1001	네트워크 연결 차단 (와이파이, 셀룰러 데이터 차단)
	1002	네트워크 타임아웃 서버 에러로 인해 유효하지 않은 HTML URL 받은 경우 서버 다운으로 인해 응답받지 못할 경우 (502 등)
onBlock	301	콘솔의 세그먼트 차단 (선의적 진입 차단)
	302	콘솔의 블랙리스트에 등록된 IP 혹은 ID로 요청한 경우 (관리자 전용 차단) 콘솔의 BotManager Basic 활성화 (악의적 진입 차단)
onClose	495	사후 대기실의 닫기 버튼 클릭
	496	사전 대기실의 닫기 버튼 클릭
	497	매크로 차단실의 닫기 버튼 클릭
	498	차단실의 닫기 버튼 클릭
	499	기본 대기실의 취소 버튼 클릭
onContinue	201	에이전트의 useNetfunnelTemplate=false 설정 및 기본 대기 시

모범 사례

중앙 집중식 구성

// 키를 한 곳에 저장
class NetfunnelConfig {
  static const String projectKey = 'service_1';
  static const String segmentKey = 'segKey_8612';
}

// 모든 곳에서 동일한 구성 사용
await Netfunnel.instance.nfStart(
  projectKey: NetfunnelConfig.projectKey,
  segmentKey: NetfunnelConfig.segmentKey,
  callback: NetfunnelHandler(),
  context: context,
);

await Netfunnel.instance.nfStop(
  projectKey: NetfunnelConfig.projectKey,
  segmentKey: NetfunnelConfig.segmentKey,
);

완전한 오류 처리

class NetfunnelHandler extends NetfunnelCallback {
  void _handleBusinessLogic() {
    // 비즈니스 로직 실행
  }

  @override
  void onSuccess(int statusCode, String message) {
    _handleBusinessLogic(); // 로직 진행
  }

  @override
  void onError(int statusCode, String message) {
    // 시스템 오류 - 서비스 실행 유지를 위해 계속 진행
    print('NetFUNNEL 시스템 오류: $message');
    _handleBusinessLogic();
  }

  @override
  void onNetworkError(int statusCode, String message) {
    // 네트워크 문제 - 계속 진행하거나 재시도
    print('NetFUNNEL 네트워크 오류: $message');
    _handleBusinessLogic(); // 계속 진행하거나 재시도 로직 구현
  }

  @override
  void onBlock(int statusCode, String message) {
    // 차단 메시지 표시
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('서비스 사용 불가'),
        content: Text('이 서비스는 일시적으로 사용할 수 없습니다.'),
      ),
    );
  }

  @override
  void onClose(int statusCode, String message) {
    // 사용자가 취소함 - 작업 필요 없음
  }
}

키 반환

// 성공적인 작업 후 키 반환
try {
  await performAction();
  await Netfunnel.instance.nfStop(
    projectKey: projectKey,
    segmentKey: segmentKey,
  );
} catch (error) {
  print('작업 실패: $error');
  // 오류 발생 시에도 키 반환
  await Netfunnel.instance.nfStop(
    projectKey: projectKey,
    segmentKey: segmentKey,
  );
}

기본 제어 함수​

Netfunnel.instance.nfStart​

Netfunnel.instance.nfStop​

구간 제어 함수​

Netfunnel.instance.nfStartSection​

Netfunnel.instance.nfStopSection​

콜백 함수​

필수 구현 함수​

선택 구현 함수​

샘플 콜백 구현​

상태 코드 참조​

모범 사례​

중앙 집중식 구성​

완전한 오류 처리​

키 반환​

관련 문서​

기본 제어 함수

Netfunnel.instance.nfStart

Netfunnel.instance.nfStop

구간 제어 함수

Netfunnel.instance.nfStartSection

Netfunnel.instance.nfStopSection

콜백 함수

필수 구현 함수

선택 구현 함수

샘플 콜백 구현

상태 코드 참조

모범 사례

중앙 집중식 구성

완전한 오류 처리

키 반환

관련 문서