Version: 4.6.1

Initialization Option Reference

Complete reference for all NetFUNNEL iOS Agent configuration options and parameters.

Complete Initialization Example

Here's a complete example showing all available configuration options:

Swift
Objective-C

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self
)

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self];

Required Parameters
Network Settings
Debugging Options
Template Options
Error Handling Options
Advanced Options

Required Parameters

These parameters are mandatory for the agent to function properly.

Parameter	Type	Description	Required	Example
`clientId`	String	Client ID from NetFUNNEL console	Yes	`"{{CLIENT_ID}}"`
`delegate`	NetfunnelDelegate	Delegate object implementing NetfunnelDelegate protocol	Yes	`self`

Bypass Mode

If clientId is missing, the agent runs in bypass mode, allowing direct access without a waiting room.

clientId

Type: String
Required: ✅ Yes
Description: Client ID from NetFUNNEL console

Swift
Objective-C

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    // ... other parameters
)

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                // ... other parameters
];

Requirements:

Must not be empty
Should match the client ID from your NetFUNNEL console
Use placeholder {{CLIENT_ID}} in documentation examples

delegate

Type: NetfunnelDelegate
Required: ✅ Yes
Description: Delegate object implementing NetfunnelDelegate protocol

Swift
Objective-C

class AppDelegate: UIResponder, UIApplicationDelegate, NetfunnelDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Netfunnel.initialize(
            clientId: "{{CLIENT_ID}}",
            delegate: self
        )
        return true
    }
}

@interface AppDelegate : UIResponder <UIApplicationDelegate, NetfunnelDelegate>
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self];
    return YES;
}

@end

Requirements:

Must implement NetfunnelDelegate protocol
Must implement required delegate methods
Should handle all callback scenarios

Network Settings

Control network behavior and timeouts for NetFUNNEL server communications.

Parameter	Type	Required	Default	Range
`networkTimeout`	NSNumber (Long)	Optional	`3000`	100–10000
`retryCount`	NSNumber (Int)	Optional	`0`	0–10
`useNetworkRecoveryMode`	NSNumber (Bool)	Optional	`false`	true/false

networkTimeout

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:

networkTimeout: 1000 → 1 second timeout
networkTimeout: 5000 → 5 second timeout

Important Notes:

Too short values may cause normal requests to be treated as timeouts
With networkTimeout: 3000 and retryCount: 3, maximum wait time is 12 seconds before nfNetworkError callback
Even if error response arrives in 35ms, retry will wait 2.965 seconds before next attempt

Swift
Objective-C

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    networkTimeout: 5000 // 5 seconds
)

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@5000];

retryCount

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

Examples:

retryCount: 0 → No retry (single attempt)
retryCount: 1 → 1 initial + 1 retry (2 total attempts)
retryCount: 2 → 1 initial + 2 retries (3 total attempts)

Important Notes:

If request succeeds during retry, retry process stops immediately
After all retry attempts are exhausted, nfNetworkError callback is triggered
Each retry respects the networkTimeout setting

Swift
Objective-C

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    retryCount: 3 // Retry up to 3 times
)

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@3000
                                  retryCount:@3];

useNetworkRecoveryMode

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)

Important Notes:

useNetworkRecoveryMode: true only maintains waiting room during network failures while waiting
If network fails before waiting starts, nfNetworkError callback is still triggered
This setting prevents users from losing their waiting position due to temporary network issues

Swift
Objective-C

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    useNetworkRecoveryMode: true // Enable network recovery
)

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                      useNetworkRecoveryMode:@true];

Debugging Options

Enable debugging and logging features.

Parameter	Type	Required	Default	Options
`printLog`	NSNumber (Bool)	Optional	`false`	`true`/`false`

printLog

Print NetFUNNEL logs to Xcode Console.

Usage:

Swift
Objective-C

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    printLog: true // Enable debug logging
)

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@3000
                                  retryCount:@0
                                    printLog:@true];

Check logs in Xcode Console:

Open Xcode Console
Filter by NetFUNNEL
Look for NetFUNNEL log messages

Log Output:

Initialization status
Network request details
Delegate method calls
Error messages
Key management events

Template Options

Control waiting room appearance and templates.

Parameter	Type	Required	Default	Options
`useNetfunnelTemplate`	NSNumber (Bool)	Optional	`true`	`true`/`false`

useNetfunnelTemplate

Use the default NetFUNNEL waiting room template.

Options:

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

Custom Template Implementation:

When useNetfunnelTemplate: false, you must implement custom waiting room UI and handle the nfContinue delegate method to receive real-time waiting information.

nfContinue Delegate Parameters:

Parameter	Type	Description	Example
`statusCode`	Int	Response code for waiting status	`201`
`message`	String	Message for waiting status	`"Continue"`
`aheadWait`	Int	Number of users ahead in queue	`{{N}}`
`behindWait`	Int	Number of users behind in queue	`{{N}}`
`waitTime`	String	Expected waiting time	`{{HH:mm:ss}}`
`progressRate`	Int	Progress percentage	`{{0~100}}`

Basic Custom Template Example:

extension AppDelegate: NetfunnelDelegate {
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        // Update your custom waiting room UI
        updateCustomWaitingRoom(aheadWait: aheadWait, behindWait: behindWait, waitTime: waitTime, progressRate: progressRate)
    }
}

Complete Custom View Controller Implementation:

1. Initialize with Custom Template:

Swift
Objective-C

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    useNetfunnelTemplate: false  // Enable custom template
)

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@3000
                                  retryCount:@0
                                    printLog:@false
                        useNetfunnelTemplate:@false];

2. Custom Waiting Room View Controller:

class CustomWaitingRoomViewController: UIViewController {
    @IBOutlet weak var waitTimeLabel: UILabel!
    @IBOutlet weak var progressBar: UIProgressView!
    @IBOutlet weak var aheadLabel: UILabel!
    @IBOutlet weak var behindLabel: UILabel!
    @IBOutlet weak var cancelButton: UIButton!
    
    var onCancel: (() -> Void)?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupUI()
    }
    
    private func setupUI() {
        view.backgroundColor = UIColor.systemBackground
        progressBar.progress = 0.0
        cancelButton.addTarget(self, action: #selector(cancelTapped), for: .touchUpInside)
    }
    
    func updateWaitingInfo(aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        DispatchQueue.main.async {
            self.aheadLabel.text = "Users ahead: \(aheadWait)"
            self.behindLabel.text = "Users behind: \(behindWait)"
            self.waitTimeLabel.text = waitTime
            self.progressBar.progress = Float(progressRate) / 100.0
        }
    }
    
    @objc private func cancelTapped() {
        dismiss(animated: true) {
            self.onCancel?()
        }
    }
}

3. Complete Delegate Implementation:

extension AppDelegate: NetfunnelDelegate {
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        DispatchQueue.main.async {
            if self.waitingRoomVC == nil {
                self.waitingRoomVC = CustomWaitingRoomViewController()
                self.waitingRoomVC?.modalPresentationStyle = .fullScreen
                self.waitingRoomVC?.onCancel = {
                    Netfunnel.shared.nfStop(projectKey: projectKey, segmentKey: segmentKey)
                }
                self.window?.rootViewController?.present(self.waitingRoomVC!, animated: true)
            }
            self.waitingRoomVC?.updateWaitingInfo(aheadWait: aheadWait, behindWait: behindWait, waitTime: waitTime, progressRate: progressRate)
        }
    }
    
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        DispatchQueue.main.async {
            self.waitingRoomVC?.dismiss(animated: true)
            self.waitingRoomVC = nil
            // Navigate to main content
        }
    }
    
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        DispatchQueue.main.async {
            self.waitingRoomVC?.dismiss(animated: true)
            self.waitingRoomVC = nil
            // Handle error
        }
    }
}

Important Notes:

View Controller creation: Create view controller only once, then update UI with updateWaitingInfo
UI updates: Always use DispatchQueue.main.async for UI modifications
Proper termination: Call Netfunnel.shared.nfStop() when closing view controller to return entry key
Limited functionality: Custom templates have restrictions on advanced waiting room features
Recommendation: Use useNetfunnelTemplate: true for full functionality unless custom UI is required

errorBypass

Type: NSNumber (Bool)
Required: ❌ No
Default: false
Description: Bypass traffic control on errors

Swift
objective-C

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    errorBypass: false // Don't bypass on errors
)

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@3000
                                  retryCount:@0
                                    printLog:@false
                        useNetfunnelTemplate:@true
                                 errorBypass:@false
                                    // ... other parameters
];

Behavior:

Value	Behavior
`false`	Maintain traffic control even on errors (recommended)
`true`	Allow users to bypass waiting room on errors

Error Handling Options

Control how errors are handled and displayed to users.

Parameter	Type	Required	Default	Options
`errorBypass`	NSNumber (Bool)	Optional	`false`	`true`/`false`

errorBypass

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)

When errorBypass: true:

nfError and nfNetworkError delegate methods are not called
Instead, nfSuccess delegate method is triggered
Only nfSuccess delegate method needs to be implemented
All error situations are bypassed

Use Cases for errorBypass: true:

Testing environments
Services where network connectivity doesn't affect core functionality
Simple event participation systems
Development and debugging scenarios

Important Warning:

errorBypass: true bypasses all error situations
Use with caution as it may hide important network issues
Not recommended for production environments with critical traffic control needs

Error Types Handled:

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

Delegate-based Integration Callbacks: When errorBypass: false, the following delegate methods are triggered:

nfNetworkError: For network-related errors (1001, 1002)
nfError: For server errors (500)
nfClose: For user cancellation (499)

Network Error Callbacks

NetFUNNEL iOS Agent provides detailed network error information through nfNetworkError delegate method.

Network Error Types:

Status Code	Message	Description
1001	Network Not Connected	Network connection blocked (WiFi/cellular data disabled)
1002	Network Timeout	Network response delay causing timeout

Network Error Handling Example:

extension AppDelegate: NetfunnelDelegate {
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        switch statusCode {
        case 1001:
            // Network connection blocked - show immediate user guidance
            showAlert(title: "Network Error", message: "네트워크 연결에 실패했습니다. 네트워크 설정을 확인해 주세요.")
        case 1002:
            // Network timeout - navigate to retry screen
            navigateToNetworkErrorScreen()
        default:
            break
        }
    }
}

Error Handling Strategy:

1001 (Network Not Connected): Immediate user guidance (alert, toast message)
1002 (Network Timeout): Navigate to error screen with retry option

Advanced Options

Additional configuration options for advanced use cases.

Parameter	Type	Required	Default	Options
`userId`	String?	Optional	`nil`	User identifier string

userId

Set user identifier for whitelist/blacklist management.

Usage:

Swift
Objective-C

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    userId: "user_67890" // User-specific identifier
)

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@3000
                                  retryCount:@0
                                    printLog:@false
                        useNetfunnelTemplate:@true
                                 errorBypass:@false
                                      userId:@"user_67890"];

Use Cases:

Whitelist specific users
Blacklist problematic users
User-specific traffic control
Analytics and monitoring

Complete Example

Here's a complete initialization example with all options:

Swift
Objective-C

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    networkTimeout: 5000,
    retryCount: 2,
    printLog: false,
    errorBypass: false,
    useNetfunnelTemplate: true,
    userId: "user_67890",
    useNetworkRecoveryMode: true
)

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@5000
                                  retryCount:@2
                                    printLog:@false
                        useNetfunnelTemplate:@true
                                 errorBypass:@false
                                      userId:@"user_67890"
                      useNetworkRecoveryMode:@true];

Installation & Initialization: Basic setup guide
API Reference: Function specifications and callbacks
Troubleshooting: Common issues and solutions
Basic Control Integration: Implementation examples
Section Control Integration: Implementation examples

Complete Initialization Example​

Table of Contents​

Required Parameters​

clientId​

delegate​

Network Settings​

networkTimeout​

retryCount​

useNetworkRecoveryMode​

Debugging Options​

printLog​

Template Options​

useNetfunnelTemplate​

errorBypass​

Error Handling Options​

errorBypass​

Network Error Callbacks​

Advanced Options​

userId​

Complete Example​

Related Documentation​

Complete Initialization Example

Table of Contents

Required Parameters

clientId

delegate

Network Settings

networkTimeout

retryCount

useNetworkRecoveryMode

Debugging Options

printLog

Template Options

useNetfunnelTemplate

errorBypass

Error Handling Options

errorBypass

Network Error Callbacks

Advanced Options

userId

Complete Example

Related Documentation