Initialization Option Reference

Complete reference for all NetFUNNEL JavaScript Agent configuration options (data-attributes).

---

Table of Contents

• Required Attributes
• Network Settings
• Storage & Cookie Options
• URL Trigger Options
• UI & Template Options
• Error Handling Options
• Debugging Options

---

Required Attributes

These attributes are mandatory for the agent to function properly.

Attribute	Description	Required
data-nf-client-id	Client identifier	Yes

---

Network Settings

Control network behavior and timeouts for NetFUNNEL server communications.

Attribute	Method	Required	Default	Range
data-nf-network-timeout	URL-triggered, Code-based	Optional	3000	100–10000
data-nf-retry-count	URL-triggered, Code-based	Optional	0	0–10
data-nf-use-network-recovery-mode	URL-triggered, Code-based	Optional	false	true/false

Network Failure Concepts

Understanding network failures and their handling is crucial for configuring NetFUNNEL properly. The behavior differs significantly between integration methods and failure causes.

Network Failure Causes:

Cause	Description	Detection	Examples
Offline	Client-side network disconnection	Network offline (detected via navigator.onLine = false)	WiFi disabled, ethernet unplugged, airplane mode
Delay	Network latency exceeding timeout	Response time > data-nf-network-timeout	Slow connection, server overload, network congestion

Failure Classification:

Failure Type	Description	Retry Behavior
Transient Failure	Temporary network issues (Offline/Delay)	Auto-retry based on data-nf-retry-count
Permanent Failure	All retry attempts exhausted	No more retries, triggers error handling

Error Handling by Integration Method:

Error handling occurs after all retry attempts are exhausted (permanent failure).

Request → Timeout → Transient Failure → Retry → Success OR Permanent Failure → Error Handling

Integration Method	5101 (Key Issuance) Failure	Service Entry	5002 (Entry Check) Failure	Service Entry
URL-triggered	No error handling (i.e. Bypass traffic control → Target page)	✅ Yes	Network Error Page (w/ Try Again button)	❌ No
Code-based	NetworkError callback (w/ 1001 or 1002 statuscode) -> No waiting room modal shown	❌ No	NetworkError callback (w/ 1001 or 1002 statuscode) → Close waiting room modal	❌ No

data-nf-network-timeout

Maximum timeout duration for NetFUNNEL server API requests before considering them transient failures.

Property	Value
Unit	milliseconds (ms)
Range	100–10000
Default	3000
Applies to	NetFUNNEL server endpoints only

Behavior:

• No response within timeout → Transient Failure
• Immediate error response → No timeout wait
• Each retry uses the same timeout setting

Examples:

• data-nf-network-timeout="1000" → 1 second timeout
• data-nf-network-timeout="5000" → 5 second timeout

data-nf-retry-count

Number of additional retry attempts for transient failures in NetFUNNEL server API calls.

Property	Value
Range	0–10
Default	0
Formula	Total attempts = (setting value) + 1
Applies to	NetFUNNEL server endpoints only

Behavior:

• Transient Failure → triggers retry (if retry count > 0)
• Permanent Failure → all retry attempts exhausted
• Each retry respects the data-nf-network-timeout setting

Examples:

• data-nf-retry-count="0" → No retry (single attempt)
• data-nf-retry-count="1" → 1 initial + 1 retry (2 total attempts)
• data-nf-retry-count="2" → 1 initial + 2 retries (3 total attempts)

URL-triggered 5101 Exception

URL-triggered 5101 requests have no retry mechanism - any single failure becomes a permanent failure, bypassing traffic control entirely.

data-nf-use-network-recovery-mode

Prevents users from being kicked out of waiting rooms due to network issues. When enabled, users stay in their waiting state (modal or waiting room) even when network problems occur, and automatically resume when connectivity is restored.

Property	Value
Default	false
Applies to	5002 (entry check) requests only
Core Benefit	No interruption to waiting experience during network issues

The Problem This Solves:

• Without recovery mode: Network failure → Error page/callback → User loses waiting position
• With recovery mode: Network failure → Stay in waiting → Auto-resume when network recovers

Behavior:

Mode	5002 (Entry Check)	User Experience
true	Stay in waiting, auto-recover	No interruption
false	Normal retry → Error handling	Error page/callback

Recovery Scenarios:

• Quick recovery: Keep existing key/sequence (maintains queue position)
• Extended outage: Get new key/sequence (position may reset)

Queue Position Management

For guaranteed queue position preservation across long outages, use the Queue Position Management feature in NetFUNNEL Console.

Network Settings Interaction Flow

How timeout, retry count, and recovery mode work together to handle network failures.

Network Settings Behavior

How network settings work together and their combined effects across different integration methods and recovery modes.

NetFUNNEL Server API Endpoints

API Endpoint	Purpose	Affected by Network Settings
5101 (Key Issuance)	Initial request for a key and waiting decision	timeout, retry-count
5002 (Entry Check)	Periodic requests while in the waiting room	timeout, retry-count, recovery-mode
5003 (Alive Notice)	Keep key active (Section Control only)	timeout, retry-count
5004 (Key Return)	Return key after service completion	timeout, retry-count

Network Error Types

Code	Type	Description
1001	Network Not Connected	Network is offline or unreachable
1002	Network Timeout	Request exceeded timeout limit

URL-triggered Integration

Scenario 1: Normal Flow (5101 Success)

Scenario 2: 5101 (Key Issuance) Network Failure (No Retry)

Scenario 3: 5002 (Entry Check) Network Failure (With Retry)

Scenario 4: Recovery Mode Enabled

Code-based Integration

Scenario 1: Normal Flow (5101 Success)

Scenario 2: 5101 (Key Issuance) Network Failure (With Retry)

Scenario 3: 5002 (Entry Check) Network Failure (With Retry)

Scenario 4: Recovery Mode Enabled

---

Storage & Cookie Options

Control how NetFUNNEL stores state values in the browser.

Attribute	Method	Required	Default	Options
data-nf-use-storage-type	URL-triggered, Code-based	Optional	both	both, session, cookie
data-nf-custom-cookie-domain	URL-triggered, Code-based	Optional	(empty)	Domain string

data-nf-use-storage-type

During traffic control, NetFUNNEL stores various state values—including keys—in the browser. This specifies the storage type used.

Options:

• both: Uses both sessionStorage and cookies for maximum compatibility
• session: Uses only sessionStorage (data lost when tab closes)
• cookie: Uses only cookies (persists across browser sessions)

data-nf-custom-cookie-domain

Force cookie domain for sharing cookies across subdomains.

Usage: Provide a domain string (e.g., .example.com) to share cookies across subdomains.

---

URL-triggered Options

Options used only with URL-triggered integration.

Attribute	Method	Required	Default	Options
data-nf-return-key	URL-triggered	Optional	true	true/false

data-nf-return-key

In the URL-triggered method, you are redirected to the NetFUNNEL waiting room and then back to the target page. This attribute controls whether to automatically return the key after entry.

Behavior:

• true (default): Key automatically returned when returning to target page
• false: Manual key return required (useful for custom integration scenarios)

---

UI & Template Options

Control waiting room appearance and templates.

Attribute	Method	Required	Default	Options
data-nf-use-netfunnel-template	URL-triggered, Code-based	Optional	true	true/false

data-nf-use-netfunnel-template

Use the default NetFUNNEL waiting room template.

Options:

• true (default): Uses NetFUNNEL's standard waiting room template
• false: Allows custom waiting room template implementation

---

Error Handling Options

Control how errors are handled and displayed to users.

Attribute	Method	Required	Default	Options
data-nf-error-bypass	URL-triggered, Code-based	Optional	false	true/false

data-nf-error-bypass

Treat Error/NetworkError as Success.

Behavior:

• false (default): Normal error handling (callbacks/redirects on errors)
• true: Treats errors as success, allowing service to continue (bypass mode)

Error Types Handled:

• Network errors (1001, 1002)
• Server errors (500)
• User cancellation (499)
• Invalid configuration errors

URL-triggered Integration Error Page: When data-nf-error-bypass="false" and network recovery mode is disabled, users see:

Network Error
The waiting process was interrupted due to a network error with your device or communication.

Please press the button below to try waiting again.
[Try Again Button]

Code-based Integration Callbacks: When data-nf-error-bypass="false", the following callbacks are triggered:

• onNetworkError: For network-related errors (1001, 1002)
• onError: For server errors (500)
• onClose: For user cancellation (499)

---

Complete Example

Here's a complete initialization script with all options:

<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>

---

Related Documentation

• Installation & Initialization: Basic setup guide
• URL-Triggered Integration: URL-based traffic control
• Code-based Integration: Function-based traffic control
• API Reference: Function specifications and callbacks
• Troubleshooting: Common issues and solutions