API Reference

Complete reference for NetFUNNEL Flutter Agent functions, callbacks, and response formats.

---

Basic Control Functions

Basic control limits the entry rate to a service. When the start function is called, a key is issued and the waiting room appears. When the stop function is called, the key is returned.

Netfunnel.instance.nfStart

Purpose: Issues a key and displays the waiting room when an operation starts.

Function Signature:

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

Parameters:

Parameter	Type	Description
projectKey	String	Basic control project key from console
segmentKey	String	Basic control segment key from console
callback	NetfunnelCallback	Custom callback function for waiting room event handling
context	BuildContext	BuildContext of the screen where the waiting room is applied

Return Value: Future<void>

Example:

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

Callback Handling: For detailed response handling, refer to the Callback Functions section.

Netfunnel.instance.nfStop

Purpose: Returns the key after entry is completed.

Function Signature:

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

Parameters:

Parameter	Type	Description
projectKey	String	Basic control project key from console
segmentKey	String	Basic control segment key from console

Return Value: Future<void>

Example:

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

Automatic Return Timeout

If the stop function is not executed, the key is automatically returned according to the segment timeout setting (default timeout: 20 seconds).

---

Section Control Functions

Section control maintains the concurrent user count within a specific application section at a fixed value. When the start function is called, a key is issued. The user is considered to be in an active section until the stop function is called, and the next user in the queue is not allowed.

Netfunnel.instance.nfStartSection

Purpose: Issues a key for section control and displays the waiting room.

Function Signature:

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

Parameters:

Parameter	Type	Description
projectKey	String	Section control project key from console
segmentKey	String	Section control segment key from console
callback	NetfunnelCallback	Custom callback function for waiting room event handling
context	BuildContext	BuildContext of the screen where the waiting room is applied

Return Value: Future<void>

Example:

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

Callback Handling: For detailed response handling, refer to the Callback Functions section.

Netfunnel.instance.nfStopSection

Purpose: Returns the key when the user exits the active section.

Function Signature:

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

Parameters:

Parameter	Type	Description
projectKey	String	Section control project key from console
segmentKey	String	Section control segment key from console

Return Value: Future<void>

Example:

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

Section Control Behavior

If the stop function is not executed, the user is considered to remain in the active section, and the next user's allowance may be delayed.

---

Callback Functions

To use the NetFUNNEL Flutter agent, you must inject callback functions into the start and stop functions.

The waiting room can be closed depending on various situations (waiting success, cancellation, blocking, error, network error, etc.), and handling scenarios for each situation can be implemented through callback functions.

Required Implementation Functions

The following three functions must be implemented:

• onSuccess: Entry allowed or bypass mode
• onError: System error occurred
• onNetworkError: Network connection problem

Optional Implementation Functions

The following functions can be implemented optionally:

• onBlock: User entry blocked
• onClose: User canceled waiting
• onContinue: UI update during waiting (only when using custom waiting room)

Sample Callback Implementation

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');
    // When entry or bypass response is received, execute existing service logic before applying NetFUNNEL.
    // ex - page navigation, function execution, API request
  }

  @override
  void onError(int statusCode, String message) {
    print('$_tag onError: $statusCode $message');
    // When system error occurs, generally execute existing service logic the same as onSuccess for smooth service use.
    // ex - page navigation, function execution, API request
  }

  @override
  void onNetworkError(int statusCode, String message) {
    print('$_tag onNetworkError: $statusCode $message');
    // When network error occurs, execute existing service logic or prompt to re-enter the queue after notification.
    // ex - page navigation, function execution, API request, modal("Network is unstable. Would you like to retry? Y/N");
  }

  @override
  void onBlock(int statusCode, String message) {
    print('$_tag onBlock: $statusCode $message');
    // When entry status is blocked, you can notify the blocking or do nothing.
    // ex - display access restriction message
  }

  @override
  void onClose(int statusCode, String message) {
    print('$_tag onClose: $statusCode $message');
    // When the close or cancel button of the waiting room is clicked, you can notify the cancellation or do nothing.
    // ex - alert("Waiting has been canceled.");
  }

  @override
  void onContinue(int statusCode, String message, int aheadWait, int behindWait, String waitTime, int progressRate) {
    print('$_tag onContinue: $statusCode $message');
    // UI update logic during waiting (only when using custom waiting room)
    // ex - update real-time waiting information to custom waiting screen
  }
}

---

Status Code Reference

Complete reference for all possible status codes and their meanings.

Callback Function	statusCode	Description
onSuccess	200	Service use allowed after normal queue passage
	300	Subscription or license expired Project/segment deactivated in console When agent's errorBypass=true is set and error occurs
	303	Request made with IP or ID registered in console's whitelist (admin-only bypass)
onError	500	Start function called without agent's initialization function Non-existent project/segment key used in agent's start function Segment deleted in console When response is partially missing due to server error
onNetworkError	1001	Network connection blocked (WiFi, cellular data blocked)
	1002	Network timeout When invalid HTML URL is received due to server error When response is not received due to server down (502, etc.)
onBlock	301	Segment blocked in console (benevolent entry blocking)
	302	Request made with IP or ID registered in console's blacklist (admin-only blocking) Console's BotManager Basic activated (malicious entry blocking)
onClose	495	Close button clicked in post-waiting room
	496	Close button clicked in pre-waiting room
	497	Close button clicked in macro blocking room
	498	Close button clicked in blocking room
	499	Cancel button clicked in default waiting room
onContinue	201	When agent's useNetfunnelTemplate=false is set and in default waiting

---

Best Practices

Centralized Configuration

// Store keys in one place
class NetfunnelConfig {
  static const String projectKey = 'service_1';
  static const String segmentKey = 'segKey_8612';
}

// Use the same configuration everywhere
await Netfunnel.instance.nfStart(
  projectKey: NetfunnelConfig.projectKey,
  segmentKey: NetfunnelConfig.segmentKey,
  callback: NetfunnelHandler(),
  context: context,
);

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

Complete Error Handling

class NetfunnelHandler extends NetfunnelCallback {
  void _handleBusinessLogic() {
    // Execute business logic
  }

  @override
  void onSuccess(int statusCode, String message) {
    _handleBusinessLogic(); // Proceed with logic
  }

  @override
  void onError(int statusCode, String message) {
    // System error - continue to maintain service execution
    print('NetFUNNEL system error: $message');
    _handleBusinessLogic();
  }

  @override
  void onNetworkError(int statusCode, String message) {
    // Network problem - continue or retry
    print('NetFUNNEL network error: $message');
    _handleBusinessLogic(); // Continue or implement retry logic
  }

  @override
  void onBlock(int statusCode, String message) {
    // Display blocking message
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('Service Unavailable'),
        content: Text('This service is temporarily unavailable.'),
      ),
    );
  }

  @override
  void onClose(int statusCode, String message) {
    // User canceled - no action needed
  }
}

Key Return

// Return key after successful operation
try {
  await performAction();
  await Netfunnel.instance.nfStop(
    projectKey: projectKey,
    segmentKey: segmentKey,
  );
} catch (error) {
  print('Operation failed: $error');
  // Return key even on error
  await Netfunnel.instance.nfStop(
    projectKey: projectKey,
    segmentKey: segmentKey,
  );
}

---

Related Documentation

• Basic Control Method: Basic control implementation guide
• Section Control Method: Section control implementation guide
• Initialization Options: All initialization parameters
• Troubleshooting: Common issues and solutions