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エージェントを使用するには、開始関数と終了関数にコールバック関数を必ず注入する必要があります。

待機室は、さまざまな状況（待機成功、キャンセル、ブロック、エラー、ネットワークエラーなど）に応じて終了でき、各状況の処理シナリオはコールバック関数を通じて実装できます。

必須実装関数

次の3つの関数を必ず実装する必要があります：

• 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');
    // 進入またはバイパス応答を受信した場合、NetFUNNELを適用する前の既存のサービスロジックを実行します。
    // 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	ネットワーク接続ブロック（WiFi、セルラーデータブロック）
	1002	ネットワークタイムアウト サーバーエラーにより無効なHTML URLを受信した場合 サーバーダウンによりレスポンスを受信できない場合（502など）
onBlock	301	コンソールのセグメントブロック（善意的な進入ブロック）
	302	コンソールのブラックリストに登録されたIPまたはIDでリクエストした場合（管理者専用ブロック） コンソールのBotManager Basic有効化（悪意のある進入ブロック）
onClose	495	事後待機室の閉じるボタンクリック
	496	事前待機室の閉じるボタンクリック
	497	マクロブロック室の閉じるボタンクリック
	498	ブロック室の閉じるボタンクリック
	499	デフォルト待機室のキャンセルボタンクリック
onContinue	201	エージェントのuseNetfunnelTemplate=false設定およびデフォルト待機時

---

ベストプラクティス

集中型構成

// キーを1箇所に保存
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,
  );
}

---

関連ドキュメント

• 基本制御方法: 基本制御実装ガイド
• 区間制御方法: 区間制御実装ガイド
• 初期化設定: すべての初期化パラメータ
• トラブルシューティング: 一般的な問題と解決方法