メインコンテンツまでスキップ
バージョン: 4.6.1-saas

トラブルシューティング

NetFUNNEL Flutter Agent統合に関する一般的な問題、解決方法、よくある質問です。

インストールの問題​

パッケージインストール失敗​

症状:

  • flutter pub getが失敗
  • パッケージが見つからない

解決方法:

  1. ネットワーク接続確認: インターネット接続状態を確認
  2. パッケージパス確認: pubspec.yamlの依存関係パスが正しいか確認
  3. tar.gzファイル確認: tar.gzファイルが正しい場所にあるか確認
  4. インデント確認: pubspec.yamlファイルのインデントが正しいか確認

初期化失敗​

症状:

  • アプリ起動時にエラー発生
  • NetFUNNELが初期化されない

解決方法:

  1. clientId確認: clientIdが正しく設定されているか確認
  2. 空文字列確認: clientIdが空文字列でないか確認
  3. 初期化位置: main.dartのmain()関数の開始部分で初期化しているか確認
  4. async/await確認: main()関数がasyncで宣言され、awaitを使用しているか確認

関数呼び出しエラー​

"nfStart is not a function"エラー​

症状:

  • NoSuchMethodError: The method 'nfStart' was called on null
  • 関数が呼び出されたときに定義されていない

解決方法:

  1. 初期化確認: Netfunnel.instance.initialize()が最初に呼び出されたか確認
  2. import確認: import 'package:netfunnel_flutter/netfunnel_flutter.dart'が正しいか確認
  3. 関数使用法: Netfunnel.instance.nfStart()形式で呼び出しているか確認

コールバックが実行されない​

症状:

  • nfStartが呼び出されたがコールバックが実行されない
  • 応答を受信しない

解決方法:

  1. ネットワーク確認: NetFUNNELサーバーへのネットワークリクエストを確認
  2. コンソールログ: printLog: trueに設定してデバッグログを確認
  3. セグメント状態: セグメントがBlock状態でないか確認
  4. 進入許可数: 進入許可数が進入を許可しているか確認

ネットワークおよび接続の問題​

ネットワークタイムアウトエラー​

症状:

  • onNetworkErrorステータスコード1002
  • リクエストがタイムアウト

解決方法:

  1. タイムアウト増加: networkTimeoutをより高い値に設定（最大10000ms）
  2. 再試行構成: retryCountを増加
  3. ネットワーク復旧: useNetworkRecoveryMode: trueを有効化
await Netfunnel.instance.initialize(
  clientId: 'your-client-id',
  networkTimeout: 5000,
  retryCount: 2,
  useNetworkRecoveryMode: true,
);

ネットワーク接続エラー​

症状:

  • onNetworkErrorステータスコード1001
  • インターネット接続なし

解決方法:

  1. 接続確認: インターネット接続状態を確認
  2. ファイアウォール: NetFUNNELドメインがブロックされていないか確認
  3. プロキシ設定: 必要に応じてプロキシを構成
  4. エラー処理: 適切なNetworkError処理を実装
class NetfunnelHandler extends NetfunnelCallback {
  @override
  void onNetworkError(int statusCode, String message) {
    // ユーザーフレンドリーなメッセージを表示
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('ネットワーク接続の問題'),
        content: Text('インターネット接続を確認してください。'),
      ),
    );
    // オプションで再試行または継続
  }
}

HTTP通信時のエラー​

症状:

  • HTTP通信時にエラー発生
  • HTTPS通信は正常に動作

解決方法:

NetFUNNEL Flutterエージェントは、デフォルトでHTTPS通信を推奨します。HTTP通信を使用する場合、プラットフォーム固有の設定を通じてHTTP通信を許可できます。

Android:

android/app/src/main/res/xml/network_security_config.xmlファイルを作成:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">{{DOMAIN_URL}}</domain>
    </domain-config>
</network-security-config>

android/app/src/main/AndroidManifest.xmlに設定を追加:

<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >
</application>

iOS:

ios/Runner/Info.plistに設定を追加:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

待機室の問題​

待機室が表示されない​

症状:

  • 待機室が表示されない
  • ユーザーが直接進行する

解決方法:

  1. 進入許可数: テストのために0に設定
  2. セグメント有効化: セグメントが有効化されているか確認
  3. テンプレート設定: useNetfunnelTemplate: trueを確認
  4. コールバック実装: 必須コールバック関数（onSuccess、onError、onNetworkError）が実装されているか確認

待機室が停止（終了しない）​

症状:

  • 待機室が表示されるが進入が許可されない
  • 無限待機

解決方法:

  1. 進入許可数: 進入許可数の値を増加
  2. セグメント状態: セグメントがBlock状態か確認
  3. ネットワーク問題: ネットワーク接続状態を確認
  4. サーバー状態: NetFUNNELサーバー状態を確認

キー管理の問題​

キーが返却されない​

症状:

  • 次のユーザーが無期限に待機
  • キューが進行しない

解決方法:

  1. nfStop呼び出し: 常にnfStop/nfStopSectionが呼び出されているか確認
  2. エラー処理: エラーシナリオでもキーを返却
  3. タイムアウト確認: セグメントタイムアウト設定を確認
try {
  await performAction();
  await Netfunnel.instance.nfStop(
    projectKey: projectKey,
    segmentKey: segmentKey,
  );
} catch (error) {
  print('操作失敗: $error');
  // エラー発生時にもキーを返却
  await Netfunnel.instance.nfStop(
    projectKey: projectKey,
    segmentKey: segmentKey,
  );
}

デバッグのヒント​

ログ確認​

デバッグのためにprintLog: trueに設定してログを確認できます:

await Netfunnel.instance.initialize(
  clientId: 'your-client-id',
  printLog: true,  // デバッグログを有効化
);

Flutterコンソールで[NF4]プレフィックスを持つログを確認してください。

エージェントバージョン確認​

エージェントのバージョンを確認するためにgetVersion()関数を使用できます:

String version = Netfunnel.instance.getVersion();
print('NetFUNNEL Agentバージョン: $version');

一般的な確認事項​

  1. 初期化確認: Netfunnel.instance.initialize()が正しく呼び出されているか確認
  2. コールバック実装: 必須コールバック関数（onSuccess、onError、onNetworkError）が実装されているか確認
  3. キー一致: 開始および終了関数で同じキーを使用しているか確認
  4. BuildContext: nfStart/nfStartSection呼び出し時に有効なBuildContextを渡しているか確認

関連ドキュメント​