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

初期化オプションリファレンス

NetFUNNEL JavaScriptエージェントのすべての構成オプション(data-attributes)の完全な参照です。

目次​

必須属性​

これらの属性はエージェントが正しく動作するために必須です。

属性説明必須
data-nf-client-idクライアント識別子はい

ネットワーク設定​

NetFUNNELサーバー通信に対するネットワーク動作およびタイムアウトを制御します。

属性方法必須デフォルト値範囲
data-nf-network-timeoutURLトリガー、コードベースオプション3000100–10000
data-nf-retry-countURLトリガー、コードベースオプション00–10
data-nf-use-network-recovery-modeURLトリガー、コードベースオプションfalsetrue/false

ネットワークエラー概念​

ネットワークエラーとその処理を理解することは、NetFUNNELを正しく構成するために重要です。動作は統合方法とエラー原因によって大きく異なります。

ネットワークエラー原因:

原因説明検出例
オフラインクライアント側ネットワーク接続切断ネットワークオフライン (navigator.onLine = falseで検出)WiFi無効化、イーサネット接続解除、機内モード
遅延タイムアウトを超えるネットワーク遅延応答時間 > data-nf-network-timeout遅い接続、サーバー過負荷、ネットワーク混雑

エラー分類:

エラータイプ説明再試行動作
一時的エラー一時的なネットワーク問題 (オフライン/遅延)data-nf-retry-countに基づいて自動再試行
永続的エラーすべての再試行試行が尽きたこれ以上再試行しない、エラー処理トリガー

統合方法別エラー処理:

エラー処理はすべての再試行試行が尽きた後(永続的エラー)に発生します。

リクエスト → タイムアウト → 一時的エラー → 再試行 → 成功または永続的エラー → エラー処理
統合方法5101 (キー発行) エラーサービス進入5002 (進入確認) エラーサービス進入
URLトリガーエラー処理なし (つまり、トラフィック制御バイパス → ターゲットページ)✅ はいネットワークエラーページ (w/ 再試行ボタン)❌ いいえ
コードベースNetworkErrorコールバック (w/ 1001または1002ステータスコード) -> 待合室モーダル表示なし❌ いいえNetworkErrorコールバック (w/ 1001または1002ステータスコード) → 待合室モーダル閉じる❌ いいえ

data-nf-network-timeout​

NetFUNNELサーバーAPIリクエストが一時的エラーと見なされる前の最大タイムアウト持続時間です。

属性値
単位ミリ秒 (ms)
範囲100–10000
デフォルト値3000
適用対象NetFUNNELサーバーエンドポイントのみ

動作:

  • タイムアウト内に応答なし → 一時的エラー
  • 即座にエラー応答 → タイムアウト待機なし
  • 各再試行は同じタイムアウト設定を使用します

例:

  • data-nf-network-timeout="1000" → 1秒タイムアウト
  • data-nf-network-timeout="5000" → 5秒タイムアウト

data-nf-retry-count​

NetFUNNELサーバーAPI呼び出しで一時的エラーに対する追加再試行試行回数です。

属性値
範囲0–10
デフォルト値0
公式総試行 = (設定値) + 1
適用対象NetFUNNELサーバーエンドポイントのみ

動作:

  • 一時的エラー → 再試行トリガー (再試行回数 > 0の場合)
  • 永続的エラー → すべての再試行試行が尽きた
  • 各再試行はdata-nf-network-timeout設定に準拠します

例:

  • data-nf-retry-count="0" → 再試行なし (単一試行)
  • data-nf-retry-count="1" → 初期1回 + 再試行1回 (総2回試行)
  • data-nf-retry-count="2" → 初期1回 + 再試行2回 (総3回試行)
URLトリガー5101例外

URLトリガー5101リクエストには再試行メカニズムがありません - 単一エラーが永続的エラーとなり、トラフィック制御を完全にバイパスします。

data-nf-use-network-recovery-mode​

ネットワーク問題によりユーザーが待合室から追い出されることを防ぎます。 有効化されると、ネットワーク問題が発生してもユーザーが待機状態(モーダルまたは待合室)に留まり、接続が回復すると自動的に再開されます。

属性値
デフォルト値false
適用対象5002 (進入確認) リクエストのみ
核心的利点ネットワーク問題中の待機体験中断なし

これが解決する問題:

  • 回復モードなし: ネットワークエラー → エラーページ/コールバック → ユーザーが待機位置を失う
  • 回復モード使用: ネットワークエラー → 待機状態維持 → ネットワーク回復時に自動再開

動作:

モード5002 (進入確認)ユーザー体験
true待機状態維持、自動回復中断なし
false正常再試行 → エラー処理エラーページ/コールバック

回復シナリオ:

  • 迅速な回復: 既存キー/シーケンス維持 (待機順番維持)
  • 長期中断: 新しいキー/シーケンス取得 (順番がリセットされる可能性がある)
待機順番維持

長期中断にわたって待機順番保存を保証するには、NetFUNNELコンソールの待機順番維持機能を使用してください。

ネットワーク設定相互作用フロー​

タイムアウト、再試行回数、回復モードが一緒に動作してネットワークエラーを処理する方法です。

ネットワーク設定動作​

ネットワーク設定が一緒に動作する方法と、さまざまな統合方法および回復モードでの結合効果です。

NetFUNNELサーバーAPIエンドポイント​

APIエンドポイント目的ネットワーク設定の影響
5101 (キー発行)キーおよび待機決定に対する初期リクエストtimeout, retry-count
5002 (進入確認)待合室にいる間の定期的なリクエストtimeout, retry-count, recovery-mode
5003 (Alive Notice)キーアクティブ状態維持 (区間コントロールのみ)timeout, retry-count
5004 (キー返却)サービス完了後にキー返却timeout, retry-count

ネットワークエラータイプ​

コードタイプ説明
1001ネットワーク接続なしネットワークがオフラインまたは接続できない
1002ネットワークタイムアウトリクエストがタイムアウト制限を超えた

シナリオ1: 正常フロー (5101成功)

シナリオ2: 5101 (キー発行) ネットワークエラー (再試行なし)

シナリオ3: 5002 (進入確認) ネットワークエラー (再試行含む)

シナリオ4: 回復モード有効化

ストレージおよびクッキーオプション​

NetFUNNELがブラウザに状態値を保存する方法を制御します。

属性方法必須デフォルト値オプション
data-nf-use-storage-typeURLトリガー、コードベースオプションbothboth, session, cookie
data-nf-custom-cookie-domainURLトリガー、コードベースオプション(空)ドメイン文字列

data-nf-use-storage-type​

トラフィック制御中、NetFUNNELはキーを含むさまざまな状態値をブラウザに保存します。これは使用されるストレージタイプを指定します。

オプション:

  • both: 最大互換性のためにsessionStorageとクッキーの両方を使用
  • session: sessionStorageのみ使用 (タブが閉じるとデータ損失)
  • cookie: クッキーのみ使用 (ブラウザセッション間で持続)

サブドメイン間のクッキー共有のためのクッキードメインを強制します。

使用方法: ドメイン文字列(例: .example.com)を提供してサブドメイン間でクッキーを共有します。

URLトリガーオプション​

URLトリガー統合でのみ使用されるオプションです。

属性方法必須デフォルト値オプション
data-nf-return-keyURLトリガーオプションtruetrue/false

data-nf-return-key​

URLトリガー方法では、NetFUNNEL待合室にリダイレクトされた後、ターゲットページに戻ります。この属性は進入後にキーを自動的に返却するかどうかを制御します。

動作:

  • true (デフォルト値): ターゲットページに戻るときにキーが自動的に返却される
  • false: 手動キー返却が必要 (カスタム統合シナリオに有用)

UIおよびテンプレートオプション​

待合室の外観とテンプレートを制御します。

属性方法必須デフォルト値オプション
data-nf-use-netfunnel-templateURLトリガー、コードベースオプションtruetrue/false

data-nf-use-netfunnel-template​

デフォルトのNetFUNNEL待合室テンプレートを使用します。

オプション:

  • true (デフォルト値): NetFUNNELの標準待合室テンプレートを使用
  • false: カスタム待合室テンプレート実装を許可

エラー処理オプション​

エラーが処理され、ユーザーに表示される方法を制御します。

属性方法必須デフォルト値オプション
data-nf-error-bypassURLトリガー、コードベースオプションfalsetrue/false

data-nf-error-bypass​

Error/NetworkErrorをSuccessとして処理します。

動作:

  • false (デフォルト値): 正常なエラー処理 (エラー時にコールバック/リダイレクト)
  • true: エラーを成功として処理してサービスが継続されるように許可 (バイパスモード)

処理されるエラータイプ:

  • ネットワークエラー (1001, 1002)
  • サーバーエラー (500)
  • ユーザーキャンセル (499)
  • 不正な構成エラー

URLトリガー統合エラーページ: data-nf-error-bypass="false"でネットワーク回復モードが無効化されている場合、ユーザーは次を表示します:

ネットワークエラー
デバイスまたは通信のネットワークエラーにより待機プロセスが中断されました。

下のボタンを押して再度待機してください。
[再試行ボタン]

コードベース統合コールバック: data-nf-error-bypass="false"の場合、次のコールバックがトリガーされます:

  • onNetworkError: ネットワーク関連エラー (1001, 1002)
  • onError: サーバーエラー (500)
  • onClose: ユーザーキャンセル (499)

完全な例​

すべてのオプションが含まれた完全な初期化スクリプトです:

<script
  src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
  data-nf-client-id="your-client-id"
  data-nf-retry-count="2"
  data-nf-network-timeout="5000"
  data-nf-use-network-recovery-mode="true"
  data-nf-use-storage-type="both"
  data-nf-custom-cookie-domain=".example.com"
  data-nf-return-key="true"
  data-nf-use-netfunnel-template="true"
  data-nf-error-bypass="false"
></script>

関連ドキュメント​