Flutter Agent

Overview

The NetFUNNEL Flutter agent is a dedicated client that communicates with the NetFUNNEL server.

Minimum Requirements

• Flutter 3.0.0 or later
• Dart 3.0.0 or later

Agent Operation Flow

Before Waiting

• Before waiting, configuration is initialized. This involves fetching configuration from the NetFUNNEL server and initializing objects from that data.
• Use the "initialization function" to initialize NetFUNNEL configuration.

While Waiting

• This is the process of showing the virtual waiting room and applying traffic waiting on the screen (Screen) where you want it.
• Use the "wait start function" to apply the virtual waiting room.

After Waiting

• This is handling after waiting ends. Situations where an end-user's wait ends are:
  • Entry success after waiting
  • Entry failure due to server or network error during waiting
  • End-user cancels waiting during wait
• Use the "callback function" and "wait stop function" to implement logic after waiting ends.

Agent Installation

The NetFUNNEL Flutter agent is provided as a tar.gz package. You must install it by adding the provided archive to your project directly; it is not published on a public repository (pub.dev).

Install Agent

Copy the tar.gz file to the project root or your desired location, then add the dependency to your Flutter project's pubspec.yaml to install the package.

warning

pubspec.yaml is interpreted as a hierarchy by indentation, so be careful with indentation.

pubspec.yaml

dependencies:
  netfunnel_flutter:
    path: ./netfunnel_flutter-{{latest}} # Path where you copied the tar.gz file

Terminal

flutter pub get

Network Permissions

On Android, add internet permission for communication with the NetFUNNEL server.

android/app/src/main/AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- Internet permission -->
    <uses-permission android:name="android.permission.INTERNET" />

</manifest>

Agent Initialization

The NetFUNNEL Flutter agent must be initialized when the app starts.

info

Perform initialization at the start of the main() function in main.dart.

import 'package:netfunnel_flutter/netfunnel_flutter.dart';

void main() async {
  // NetFUNNEL agent initialization
  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());
}

Parameter	Type	Description	Required	Condition
clientId	String	User unique identifier	O	Cannot be empty string
serverUrl	String	NetFUNNEL server address	X	None (default address used)
errorUrl	String	NetFUNNEL error page HTML address	X	None (default address used)
networkTimeout	int	Maximum time to wait for network response	X	Default: 3,000ms<br/>Max: 10,000ms<br/>Min: 100ms
retryCount	int	Number of retries on network request failure	X	Default: 0<br/>Max: 10<br/>Min: 0
printLog	bool	Whether to output logs for debugging	X	Default: false
errorBypass	bool	Whether to bypass on error	X	Default: false
useNetfunnelTemplate	bool	Whether to use the custom NetFUNNEL waiting room from the console	X	Default: true
userId	String	End-user unique identifier for blacklist/whitelist	X	Default: null
useNetworkRecoveryMode	bool	Whether to keep the waiting room and retry when the connection is lost	X	Default: false
profile	String	User environment (prod_tokyo, prod_us_east)	X	Default: prod_tokyo

Agent Application

You can apply the waiting room to specific screens using the functions provided by the NetFUNNEL Flutter agent.

info

Project key and segment key for the start and stop functions can be found in the Console project tab.

Callback Function

To use the NetFUNNEL Flutter agent, you must provide a callback to the start and stop functions.

The waiting room can end in various situations (wait success, cancel, block, error, network error, etc.). Implement handling for each case in the callback.

abstract class: NetfunnelCallback

Callback	Required
onSuccess	Required
onError	Required
onNetworkError	Required
onBlock	Optional
onClose	Optional
onContinue	Optional

Callback	Status code	Scenario
onSuccess	200	Passed queue and service access allowed
onSuccess	300	Subscription/license expired; project/segment deactivated; agent errorBypass=true and error occurred
onSuccess	303	Request from IP or ID on console whitelist (admin bypass)
onError	500	Start called without init; invalid project/segment key; segment deleted; partial server response
onNetworkError	1001	Network connection blocked (Wi‑Fi, cellular)
onNetworkError	1002	Network timeout; invalid HTML URL; server down (502, etc.)
onBlock	301	Segment block (voluntary entry block)
onBlock	302	Request from IP or ID on blacklist (admin block); BotManager Basic enabled
onClose	495	Post-waiting room close button clicked
onClose	496	Pre-waiting room close button clicked
onClose	497	Macro block room close button clicked
onClose	498	Block room close button clicked
onClose	499	Default waiting room cancel button clicked
onContinue	201	Agent useNetfunnelTemplate=false and default wait

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');
    /// Logic when queue is passed (e.g. navigate to service screen)
  }

  @override
  void onError(int statusCode, String message) {
    print('$_tag onError: $statusCode $message');
    /// Logic on error (e.g. show error or bypass)
  }

  @override
  void onNetworkError(int statusCode, String message) {
    print('$_tag onNetworkError: $statusCode $message');
    /// Logic on network error (e.g. guide to reconnect or retry screen)
  }

  @override
  void onBlock(int statusCode, String message) {
    print('$_tag onBlock: $statusCode $message');
    /// Logic when entry is blocked (e.g. show access denied)
  }

  @override
  void onClose(int statusCode, String message) {
    print('$_tag onClose: $statusCode $message');
    /// Logic when user cancels wait (e.g. show exit message)
  }

  @override
  void onContinue(int statusCode, String message, int aheadWait, int behindWait, String waitTime, int progressRate) {
    print('$_tag onContinue: $statusCode $message');
    /// UI update while waiting (only when using custom waiting room)
  }
}

Basic Control

Start Function

To apply the waiting room on a specific screen (Widget or Page), use the "wait start function" to show the virtual waiting room. Basic control is useful to apply waiting when an end-user enters a specific screen, to manage server load and end-user experience.

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

Parameter	Type	Description	Required
projectKey	String	NetFUNNEL console Basic Control project key	O
segmentKey	String	NetFUNNEL console Basic Control segment key	O
callback	Function	User-defined callback for waiting room events	O
context	BuildContext	BuildContext of the screen where the waiting room is applied	O

Stop Function

When basic control wait completes successfully, implement both of the following:

• Code to enter the service after waiting (navigate to the target page)
• Code that calls the "wait stop function" after business logic to return the entry key to the NetFUNNEL server

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

Parameter	Type	Description	Required
projectKey	String	NetFUNNEL console Basic Control project key	O
segmentKey	String	NetFUNNEL console Basic Control segment key	O

Section Control

Section control applies a waiting state between entry and exit of a specific page. With section control, users can maintain a smooth flow in a specific section of the page.

• After entering an event page, purchasing a product, and clicking the payment complete button
• From end-user login until logout

To start section control, use the "section start function" to define the start of the control section. This keeps the waiting state in that section's flow.

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

Parameter	Type	Description	Required
projectKey	String	NetFUNNEL console Section Control project key	O
segmentKey	String	NetFUNNEL console Section Control segment key	O
callback	Function	User-defined callback for waiting room events	O
context	BuildContext	BuildContext of the screen where the waiting room is applied	O

Stop Function

When section control wait completes successfully, you can implement:

• Code to enter the service after waiting (navigate to the target page)

To end section control, use the "section stop function" to define the end of the section. This ends the end-user's section control and allows the next end-user to enter.

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

Parameter	Type	Description	Required
projectKey	String	NetFUNNEL console Section Control project key	O
segmentKey	String	NetFUNNEL console Section Control segment key	O