Version: 4.6.1

iOS Agent API Reference

Complete reference for NetFUNNEL 4 iOS Agent functions, delegates, and response formats.

Overview

The NetFUNNEL iOS Agent provides a comprehensive API for implementing traffic control in iOS applications. This reference covers all available functions, delegate methods, and configuration options.

Core Functions

Initialize Agent

Initializes the NetFUNNEL agent with configuration parameters.

Swift
Objective-C

Netfunnel.initialize(
    clientId: String,
    delegate: NetfunnelDelegate,
    networkTimeout: NSNumber?,
    retryCount: NSNumber?,
    printLog: NSNumber?,
    useNetfunnelTemplate: NSNumber?,
    errorBypass: NSNumber?,
    userId: String?,
    useNetworkRecoveryMode: NSNumber?
)

[agent initializeWithClientId:(NSString *)clientId
                                delegate:(id<NetfunnelDelegate>)delegate
                              networkTimeout:(NSNumber *)networkTimeout
                                  retryCount:(NSNumber *)retryCount
                                    printLog:(NSNumber *)printLog
                        useNetfunnelTemplate:(NSNumber *)useNetfunnelTemplate
                                 errorBypass:(NSNumber *)errorBypass
                                      userId:(NSString *)userId
                      useNetworkRecoveryMode:(NSNumber *)useNetworkRecoveryMode];

Parameters:

Parameter	Type	Required	Default	Description
`clientId`	`String`	✅	-	Client ID from NetFUNNEL console
`delegate`	`NetfunnelDelegate`	✅	-	Delegate object implementing protocol
`networkTimeout`	`NSNumber (Long)`	❌	3000	Network timeout (ms), Min: 100, Max: 10000
`retryCount`	`NSNumber (Int)`	❌	0	Retry attempts, Min: 0, Max: 10
`printLog`	`NSNumber (Bool)`	❌	false	Enable debug logging
`useNetfunnelTemplate`	`NSNumber (Bool)`	❌	true	Use waiting room templates from Console
`errorBypass`	`NSNumber (Bool)`	❌	false	Bypass on error
`userId`	`String`	❌	N/A	Value for White/Black-list matching
`useNetworkRecoveryMode`	`NSNumber (Bool)`	❌	false	Keep waiting room open during network issues

Basic Control Functions

Start Basic Control

Starts Basic Control for entry speed limiting.

Swift
Objective-C

Netfunnel.shared.nfStart(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStartWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

Parameters:

Parameter	Type	Required	Description
`projectKey`	`String`	✅	Project key for Basic Control in Console
`segmentKey`	`String`	✅	Segment key for Basic Control in Console

Stop Basic Control

Stops Basic Control and returns the entry key.

Swift
Objective-C

Netfunnel.shared.nfStop(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStopWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

Parameters:

Parameter	Type	Required	Description
`projectKey`	`String`	✅	Project key for Basic Control
`segmentKey`	`String`	✅	Segment key for Basic Control

Section Control Functions

Start Section Control

Starts Section Control for concurrent user management.

Swift
Objective-C

Netfunnel.shared.nfStartSection(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStartSectionWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

Parameters:

Parameter	Type	Required	Description
`projectKey`	`String`	✅	Project key for Section Control in Console
`segmentKey`	`String`	✅	Segment key for Section Control in Console

Stop Section Control

Stops Section Control and returns the section key.

Swift
Objective-C

Netfunnel.shared.nfStopSection(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStopSectionWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

Parameters:

Parameter	Type	Required	Description
`projectKey`	`String`	✅	Project key for Section Control
`segmentKey`	`String`	✅	Segment key for Section Control

Utility Functions

Get Version

Returns the NetFUNNEL iOS Agent version.

Swift
Objective-C

let version = Netfunnel.shared.getVersion()

NSString *version = [[Netfunnel shared] getVersion];

Return Value:

Type	Description
`String`	NetFUNNEL Agent version string

Delegate Protocol

The NetfunnelDelegate protocol defines callback methods for handling NetFUNNEL events.

Required Methods

nfSuccess

Called when user successfully passes the queue.

Swift
Objective-C

func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfSuccessWithProjectKey:(NSString *)projectKey
                      segmentKey:(NSString *)segmentKey
                      statusCode:(NSInteger)statusCode
                         message:(NSString *)message;

Parameters:

Parameter	Type	Description
`projectKey`	`String`	Project key
`segmentKey`	`String`	Segment key
`statusCode`	`Int`	Status code (200, 300, 303)
`message`	`String`	Success message

Status Codes:

Code	Scenario
200	Passed the queue; access allowed
300	Subscription/license expired; Project/Segment disabled; `errorBypass = true` with error
303	Request from IP/ID in Whitelist (admin bypass)

nfError

Called when a system error occurs.

Swift
Objective-C

func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfErrorWithProjectKey:(NSString *)projectKey
                    segmentKey:(NSString *)segmentKey
                    statusCode:(NSInteger)statusCode
                       message:(NSString *)message;

Parameters:

Parameter	Type	Description
`projectKey`	`String`	Project key
`segmentKey`	`String`	Segment key
`statusCode`	`Int`	Status code (500)
`message`	`String`	Error message

Status Codes:

Code	Scenario
500	Start called without initialize; invalid keys; segment deleted; partial server response

nfNetworkError

Called when a network error occurs.

Swift
Objective-C

func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfNetworkErrorWithProjectKey:(NSString *)projectKey
                           segmentKey:(NSString *)segmentKey
                           statusCode:(NSInteger)statusCode
                              message:(NSString *)message;

Parameters:

Parameter	Type	Description
`projectKey`	`String`	Project key
`segmentKey`	`String`	Segment key
`statusCode`	`Int`	Status code (1001, 1002)
`message`	`String`	Network error message

Status Codes:

Code	Scenario
1001	Network disconnected (Wi-Fi/Cellular off)
1002	Network timeout; invalid HTML URL; server down (e.g., 502)

Optional Methods

nfBlock

Called when user is blocked.

Swift
Objective-C

func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfBlockWithProjectKey:(NSString *)projectKey
                   segmentKey:(NSString *)segmentKey
                   statusCode:(NSInteger)statusCode
                      message:(NSString *)message;

Status Codes:

Code	Scenario
301	Segment blocked in Console (benevolent block)
302	Request from IP/ID in Blacklist; BotManager Basic enabled (malicious block)

nfClose

Called when user closes the waiting room.

Swift
Objective-C

func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfCloseWithProjectKey:(NSString *)projectKey
                   segmentKey:(NSString *)segmentKey
                   statusCode:(NSInteger)statusCode
                      message:(NSString *)message;

Status Codes:

Code	Scenario
495	Post-waiting room: close button clicked
496	Pre-waiting room: close button clicked
497	Macro-block room: close button clicked
498	Block room: close button clicked
499	Default waiting room: cancel button clicked

nfContinue

Called when using custom waiting UI (useNetfunnelTemplate = false).

Swift
Objective-C

func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int)

- (void)nfContinueWithProjectKey:(NSString *)projectKey
                      segmentKey:(NSString *)segmentKey
                      statusCode:(NSInteger)statusCode
                         message:(NSString *)message
                       aheadWait:(NSInteger)aheadWait
                      behindWait:(NSInteger)behindWait
                        waitTime:(NSString *)waitTime
                    progressRate:(NSInteger)progressRate;

Parameters:

Parameter	Type	Description
`projectKey`	`String`	Project key
`segmentKey`	`String`	Segment key
`statusCode`	`Int`	Status code (201)
`message`	`String`	Continue message
`aheadWait`	`Int`	Number of users ahead in queue
`behindWait`	`Int`	Number of users behind in queue
`waitTime`	`String`	Estimated wait time
`progressRate`	`Int`	Progress percentage (0-100)

Status Codes:

Code	Scenario
201	When `useNetfunnelTemplate = false` (custom waiting UI in use)

nfComplete

Called when key return to server completes.

Swift
Objective-C

func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfCompleteWithProjectKey:(NSString *)projectKey
                      segmentKey:(NSString *)segmentKey
                      statusCode:(NSInteger)statusCode
                         message:(NSString *)message;

Status Codes:

Code	Scenario
200	Successfully returned entry key to server
500	Failed to return entry key to server

Best Practices

1. Always Use Main Queue for UI Updates

func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    DispatchQueue.main.async {
        // UI updates here
        self.updateUI()
    }
}

2. Implement All Required Delegate Methods

class ViewController: UIViewController, NetfunnelDelegate {
    // Required methods
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    
    // Optional methods (implement as needed)
    func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) { }
    func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
}

3. Handle Errors Gracefully

func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    // Log error for debugging
    print("NetFUNNEL Error: \(statusCode) - \(message)")
    
    // Proceed with original logic for service availability
    DispatchQueue.main.async {
        self.proceedWithOriginalLogic()
    }
}

4. Return Keys Promptly

// Basic Control - return key immediately after action
private func performAction() {
    // Action logic
    actionService.performAction { [weak self] result in
        // Return key immediately after action completes
        Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
    }
}

// Section Control - return key when entire section completes
private func completeSection() {
    // Section completion logic
    sectionService.completeSection { [weak self] result in
        if result.success {
            // Return key when section fully completes
            Netfunnel.shared.nfStopSection(projectKey: "project", segmentKey: "segment")
        }
    }
}

5. Use Descriptive Project/Segment Keys

// ✅ Good: Descriptive keys
Netfunnel.shared.nfStart(projectKey: "ecommerce_app", segmentKey: "checkout_protection")

// ❌ Bad: Generic keys
Netfunnel.shared.nfStart(projectKey: "project1", segmentKey: "segment1")

Error Handling

Common Error Scenarios

Error Type	Status Code	Cause	Solution
System Error	500	Invalid keys, segment deleted	Check console configuration
Network Error	1001	No internet connection	Enable network recovery mode
Network Error	1002	Server timeout/down	Check server status
Block	301	Segment blocked	Check segment activation
Block	302	User in blacklist	Check user status

Error Recovery Strategies

func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    switch statusCode {
    case 1001: // Network disconnected
        // Show offline message, enable network recovery mode
        showOfflineMessage()
    case 1002: // Network timeout/server down
        // Show retry option, check server status
        showRetryOption()
    default:
        // Log unknown network error
        print("Unknown network error: \(statusCode)")
    }
}

Performance Considerations

1. Minimize Delegate Method Overhead

// ✅ Good: Efficient delegate implementation
func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    DispatchQueue.main.async { [weak self] in
        self?.handleSuccess()
    }
}

// ❌ Bad: Heavy operations in delegate
func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    // Heavy operations should be moved to separate methods
    performHeavyOperation()
    updateDatabase()
    sendAnalytics()
}

2. Use Weak References

class ViewController: UIViewController, NetfunnelDelegate {
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        DispatchQueue.main.async { [weak self] in
            self?.handleSuccess()
        }
    }
}

3. Optimize Key Return Timing

// ✅ Good: Return key at optimal time
override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
}

// ❌ Bad: Return key too early
override func viewDidLoad() {
    super.viewDidLoad()
    Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment") // Too early!
}

Debugging

Enable Debug Logging

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

Monitor Network Requests

Use Xcode's Network Inspector or tools like Charles Proxy to monitor NetFUNNEL requests:

Start requests: Look for requests to NetFUNNEL server
Key return requests: Look for nfStop/nfStopSection requests
Timeout extension: Look for 5003 requests (Section Control)

Common Debug Scenarios

Issue	Debug Steps
Waiting room doesn't appear	Check Limited Inflow = 0, segment activation
Key not returned	Verify `nfStop`/`nfStopSection` called
App crashes in delegate	Check UI updates on main queue
Network errors	Enable `printLog = true`, check connectivity

Overview​

Core Functions​

Initialize Agent​

Basic Control Functions​

Start Basic Control​

Stop Basic Control​

Section Control Functions​

Start Section Control​

Stop Section Control​

Utility Functions​

Get Version​

Delegate Protocol​

Required Methods​

nfSuccess​

nfError​

nfNetworkError​

Optional Methods​

nfBlock​

nfClose​

nfContinue​

nfComplete​

Best Practices​

1. Always Use Main Queue for UI Updates​

2. Implement All Required Delegate Methods​

3. Handle Errors Gracefully​

4. Return Keys Promptly​

5. Use Descriptive Project/Segment Keys​

Error Handling​

Common Error Scenarios​

Error Recovery Strategies​

Performance Considerations​

1. Minimize Delegate Method Overhead​

2. Use Weak References​

3. Optimize Key Return Timing​

Debugging​

Enable Debug Logging​

Monitor Network Requests​

Common Debug Scenarios​

Overview

Core Functions

Initialize Agent

Basic Control Functions

Start Basic Control

Stop Basic Control

Section Control Functions

Start Section Control

Stop Section Control

Utility Functions

Get Version

Delegate Protocol

Required Methods

nfSuccess

nfError

nfNetworkError

Optional Methods

nfBlock

nfClose

nfContinue

nfComplete

Best Practices

1. Always Use Main Queue for UI Updates

2. Implement All Required Delegate Methods

3. Handle Errors Gracefully

4. Return Keys Promptly

5. Use Descriptive Project/Segment Keys

Error Handling

Common Error Scenarios

Error Recovery Strategies

Performance Considerations

1. Minimize Delegate Method Overhead

2. Use Weak References

3. Optimize Key Return Timing

Debugging

Enable Debug Logging

Monitor Network Requests

Common Debug Scenarios