Flutter Agent

概要

NetFUNNEL Flutter エージェントは、NetFUNNEL サーバーと通信する専用クライアントです。

最小要件

• Flutter 3.0.0 以上
• Dart 3.0.0 以上

エージェントの動作フロー

待機前

• 待機前に、設定情報を初期化します。NetFUNNEL サーバーから設定情報を取得し、その情報に基づいてオブジェクトを初期化する過程です。
• 「初期化関数」を使用して NetFUNNEL の設定情報を初期化してください。

待機中

• 仮想待機室を表示し、トラフィック待機を適用したい画面（Screen）で待機させる過程です。
• 「待機開始関数」を使用して仮想待機室を適用してください。

待機後

• 待機終了後の処理です。エンドユーザーの待機が終了する状況は次のとおりです。
  • 待機完了後の進入成功
  • 待機中のサーバーエラーまたはネットワークエラーによる進入失敗
  • 待機中のエンドユーザーによる待機キャンセル
• 「コールバック関数」と「待機終了関数」を使用して、待機終了後のロジックを実装してください。

エージェントのインストール

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<br/>最大: 10,000ms<br/>最小: 100ms
retryCount	int	ネットワークリクエスト失敗時のリトライ回数	X	既定: 0<br/>最大: 10<br/>最小: 0
printLog	bool	デバッグ用ログ出力の有無	X	既定: false
errorBypass	bool	エラー時のバイパス有無	X	既定: false
useNetfunnelTemplate	bool	コンソールでカスタムした NetFUNNEL 待機室を使用するか	X	既定: true
userId	String	ブラックリスト・ホワイトリスト用のエンドユーザー固有識別子	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	待機列を通過しサービス利用が許可された場合
onSuccess	300	サブスクリプション／ライセンス期限切れ、プロジェクト／セグメント無効化、errorBypass=true でエラー時
onSuccess	303	コンソールのホワイトリストに登録された IP または ID によるリクエスト（管理者バイパス）
onError	500	初期化なしで開始関数呼び出し、無効なプロジェクト／セグメントキー、セグメント削除、サーバー応答一部欠損
onNetworkError	1001	ネットワーク接続遮断（Wi‑Fi、携帯データ）
onNetworkError	1002	ネットワークタイムアウト、無効な HTML URL、サーバーダウン（502 等）
onBlock	301	セグメントブロック（任意進入ブロック）
onBlock	302	ブラックリストに登録された IP または ID によるリクエスト（管理者ブロック）、BotManager Basic 有効
onClose	495	事後待機室の閉じるボタン押下
onClose	496	事前待機室の閉じるボタン押下
onClose	497	マクロブロック室の閉じるボタン押下
onClose	498	ブロック室の閉じるボタン押下
onClose	499	既定待機室のキャンセルボタン押下
onContinue	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');
    /// 待機列通過時の処理（例: サービス画面へ遷移）
  }

  @override
  void onError(int statusCode, String message) {
    print('$_tag onError: $statusCode $message');
    /// エラー時の処理（例: エラー表示またはバイパス）
  }

  @override
  void onNetworkError(int statusCode, String message) {
    print('$_tag onNetworkError: $statusCode $message');
    /// ネットワークエラー時の処理（例: 再接続案内または再試行画面へ）
  }

  @override
  void onBlock(int statusCode, String message) {
    print('$_tag onBlock: $statusCode $message');
    /// 進入ブロック時の処理（例: アクセス制限メッセージ表示）
  }

  @override
  void onClose(int statusCode, String message) {
    print('$_tag onClose: $statusCode $message');
    /// ユーザーが待機をキャンセルした場合の処理（例: 終了案内表示）
  }

  @override
  void onContinue(int statusCode, String message, int aheadWait, int behindWait, String waitTime, int progressRate) {
    print('$_tag onContinue: $statusCode $message');
    /// 待機中の UI 更新（自前のカスタム待機室使用時のみ）
  }
}

基本制御

開始関数

特定の画面（Widget または Page）に待機室を適用するには、「待機開始関数」で仮想待機室を表示します。基本制御は、エンドユーザーが特定画面に進入したときに待機を適用し、サーバー負荷とエンドユーザー体験を管理するのに役立ちます。

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

区間制御

区間制御は、特定ページの進入から退出までの間、待機状態を維持する方式です。区間制御により、ページの特定区間でスムーズなフローを維持できます。

• イベントページ進入後、商品購入から支払い完了ボタン押下まで
• エンドユーザーのログインからログアウトまで

区間制御を開始するには、「区間開始関数」で制御区間の開始を定義します。これにより、その区間のフローで待機状態が維持されます。

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

終了関数

区間制御の待機が正常に完了した場合、次を実装できます。

• 待機後にサービスへ進入するコード（対象ページへ遷移するコード）

区間制御を終了するには、「区間終了関数」で区間の終了を定義します。これにより、該当エンドユーザーの区間制御が終了し、次のエンドユーザーが進入できます。

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

パラメータ	型	説明	必須
projectKey	String	NetFUNNEL コンソールの区間制御プロジェクトキー	O
segmentKey	String	NetFUNNEL コンソールの区間制御セグメントキー	O