iOS Agent Troubleshooting

Comprehensive guide for resolving common issues with NetFUNNEL 4 iOS Agent.

---

Quick Diagnosis

Common Issues Checklist

Before diving into specific solutions, check these common issues:

• Framework properly added to project
• Initialization called in AppDelegate
• Delegate methods implemented correctly
• Project/Segment keys match console exactly
• Limited Inflow set to 0 for testing
• Segment activated in console
• Network connectivity available

---

Installation Issues

Framework Not Found

Error: No such module 'Netfunnel_iOS'

Symptoms:

• Build fails with import error
• Xcode shows red error indicators
• Module not recognized

Solutions:

1. Verify Framework Registration:

   • Go to Project → General → Frameworks, Libraries, and Embedded Content
   • Ensure netfunnel_ios.xcframework appears in the list
   • Check for question marks (?) next to framework

2. Fix Framework Path:

   Right-click framework → Source Control → Add netfunnel_ios.xcframework

3. Clean and Rebuild:

   • Product → Clean Build Folder (⌘+Shift+K)
   • Product → Build (⌘+B)

4. Check Framework Location:

   • Ensure framework is in Frameworks folder
   • Verify file path is correct

Build Errors

Error: Build fails with framework-related errors

Symptoms:

• Compilation errors
• Linker errors
• Architecture mismatch errors

Solutions:

1. Check iOS Deployment Target:

   • Ensure target is iOS 12.0 or later
   • Project → Build Settings → iOS Deployment Target

2. Verify Architecture Compatibility:

   • Framework supports arm64, armv7
   • Check Build Settings → Architectures

3. Clean Build Folder:

   Product → Clean Build Folder

4. Check Framework Integrity:

   • Re-download framework from console
   • Verify file size and checksum

Privacy Manifest Issues

Error: Invalid privacy manifest

Symptoms:

• Build fails with privacy manifest error
• App Store rejection

Solutions:

1. Update to Latest Version:

   • Download latest framework from console
   • Version 4.3.2-onprem includes updated privacy manifest

2. Check Framework Version:

   let version = Netfunnel.shared.getVersion()
   print("NetFUNNEL Version: \(version)")

---

Initialization Issues

Agent Doesn't Initialize

Error: Agent bypasses traffic control

Symptoms:

• No waiting room appears
• Users bypass queue
• No NetFUNNEL logs

Solutions:

1. Check Initialization Order:

   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
       // Initialize BEFORE super.onCreate()
       Netfunnel.initialize(...)
       return true
   }

2. Verify Required Parameters:

   • clientId must not be empty
   • delegate must implement protocol

3. Enable Debug Logging:

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

4. Check Network Connectivity:

   • Verify network connection is available
   • Test with browser or curl

Invalid Client ID

Error: Initialization fails

Symptoms:

• nfNetworkError callbacks
• Initialization fails
• Agent runs in bypass mode

Solutions:

1. Verify Client ID Format:

   // ✅ Correct format
   clientId: "{{CLIENT_ID}}"
   
   // ❌ Incorrect formats
   clientId: "" // Empty client ID
   clientId: nil // Missing client ID

2. Check Client ID from Console:

   • Verify client ID matches the one from NetFUNNEL console
   • Ensure client ID is copied correctly

3. Check Network Permissions:

   • Ensure NSAppTransportSecurity allows HTTPS
   • Verify internet permission in Info.plist

---

Runtime Issues

App Crashes in Delegate Callbacks

Error: App crashes when delegate methods are called

Symptoms:

• App crashes during waiting room
• Crashes in nfSuccess, nfError, etc.
• Thread-related crashes

Solutions:

1. 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 Methods:

   class ViewController: UIViewController, NetfunnelDelegate {
       // Required methods
       func nfSuccess(...) { }
       func nfError(...) { }
       func nfNetworkError(...) { }
   }

3. Use Weak References:

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

Waiting Room Doesn't Appear

Error: No waiting room shown despite traffic control

Symptoms:

• Users enter immediately
• No queue experience
• Traffic control not working

Solutions:

1. Check Limited Inflow Setting:

   • Set to 0 for testing
   • Console → Segment → Limited Inflow

2. Verify Segment Activation:

   • Console → Segment → Segment Activation: ✅ Enabled
   • Entry Status: Waiting

3. Check Project/Segment Keys:

   // Verify keys match console exactly
   Netfunnel.shared.nfStart(projectKey: "exact_project_key", segmentKey: "exact_segment_key")

4. Enable Debug Logging:

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

Key Not Returned

Error: Keys not returned to server

Symptoms:

• Users stuck in queue
• No nfComplete callbacks
• Server shows keys not returned

Solutions:

1. Ensure Stop Functions Called:

   // Basic Control
   override func viewWillDisappear(_ animated: Bool) {
       super.viewWillDisappear(animated)
       Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
   }
   
   // Section Control
   func completeSection() {
       Netfunnel.shared.nfStopSection(projectKey: "project", segmentKey: "segment")
   }

2. Check Network Connectivity:

   • Verify server is reachable
   • Check for network timeouts

3. Monitor Network Requests:

   • Use Xcode Network Inspector
   • Look for nfStop/nfStopSection requests

---

Configuration Issues

Wrong Control Type

Error: Unexpected behavior with control type

Symptoms:

• Basic Control behaving like Section Control
• Section Control behaving like Basic Control
• Wrong waiting room behavior

Solutions:

1. Verify Segment Configuration:

   • Console → Segment → Control Type
   • Ensure matches your implementation

2. Check Function Calls:

   // Basic Control
   Netfunnel.shared.nfStart(projectKey: "project", segmentKey: "segment")
   Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
   
   // Section Control
   Netfunnel.shared.nfStartSection(projectKey: "project", segmentKey: "segment")
   Netfunnel.shared.nfStopSection(projectKey: "project", segmentKey: "segment")

Network Timeout Issues

Error: Frequent network timeouts

Symptoms:

• nfNetworkError callbacks
• Users experiencing delays
• Server timeouts

Solutions:

1. Increase Network Timeout:

   Netfunnel.initialize(
       clientId: "{{CLIENT_ID}}",
       delegate: self,
       networkTimeout: 5000 // Increase from default 3000
   )

2. Enable Network Recovery:

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

3. Check Server Performance:

   • Monitor server response times
   • Check server logs for errors

---

Performance Issues

Slow App Performance

Error: App becomes slow with NetFUNNEL

Symptoms:

• UI lag
• Slow response times
• Memory issues

Solutions:

1. Disable Debug Logging:

   Netfunnel.initialize(
       clientId: "{{CLIENT_ID}}",
       delegate: self,
       printLog: false // Disable for production
   )

2. Optimize Delegate Methods:

   func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
       DispatchQueue.main.async { [weak self] in
           // Lightweight operations only
           self?.handleSuccess()
       }
   }

3. Reduce Retry Count:

   Netfunnel.initialize(
       clientId: "{{CLIENT_ID}}",
       delegate: self,
       retryCount: 1 // Reduce from default
   )

Memory Issues

Error: Memory leaks or high memory usage

Symptoms:

• Memory warnings
• App crashes
• High memory usage

Solutions:

1. Use Weak References:

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

2. Proper Cleanup:

   override func viewWillDisappear(_ animated: Bool) {
       super.viewWillDisappear(animated)
       // Clean up resources
       Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
   }

---

Debugging Techniques

Enable Debug Logging

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

Log Output Includes:

• Network requests and responses
• Delegate method calls
• Error conditions
• Key management events

Monitor Network Requests

1. Xcode Network Inspector:

   • Debug → Attach to Process
   • Network tab shows all requests

2. Charles Proxy:

   • Monitor HTTPS requests
   • View request/response details

3. Console Logs:

   // Look for NetFUNNEL messages
   NSLog(@"NetFUNNEL: %@", message);

Test Different Scenarios

1. Test Waiting Room:

   • Set Limited Inflow to 0
   • Verify waiting room appears

2. Test Entry:

   • Set Limited Inflow to 1
   • Verify immediate entry

3. Test Key Return:

   • Monitor network requests
   • Verify nfComplete callbacks

---

Common Error Codes

Success Codes

Code	Meaning	Action
200	Successfully passed queue	Proceed with normal flow
300	Bypass due to error/expiration	Proceed with normal flow
303	Whitelist bypass	Proceed with normal flow

Error Codes

Code	Meaning	Action
500	System error	Proceed with normal flow
1001	Network disconnected	Enable network recovery
1002	Network timeout/server down	Check server status

Block Codes

Code	Meaning	Action
301	Segment blocked	Check segment activation
302	User blacklisted	Check user status

Close Codes

Code	Meaning	Action
495-499	User closed waiting room	Handle user cancellation

---

FAQ

Q: The agent doesn't build (Invalid privacy manifest)

A: From version 4.3.2-onprem, the agent's privacyInfo was updated due to Apple policy changes. Ensure you're using the latest agent version.

Q: The app crashes in delegate callbacks

A: If you manipulate UI inside delegate callbacks, ensure the code runs on the main thread using DispatchQueue.main.async.

Q: I want to see debug logs

A: Enable logs by setting printLog: true in the initialize function. Use this only while debugging and set it to false for production builds.

Q: The waiting room doesn't appear

A: If Entry Allowance is 0, the waiting room must appear and no users are allowed to enter. Set Console → Segment Settings → Basic Settings → Entry Allowance to 0 to force the waiting room to show.

Q: I want to update UI from delegate callbacks

A: NetFUNNEL callbacks are asynchronous. If you call UI elements directly inside these callbacks, your app may behave unexpectedly or crash. Always dispatch to the main queue for UI updates.

Q: How to check the agent version

A: Use getVersion() to retrieve the NetFUNNEL iOS Agent version.

---

Getting Help

Before Contacting Support

1. Check this troubleshooting guide
2. Enable debug logging (printLog: true)
3. Verify configuration matches console
4. Test with minimal configuration
5. Check network connectivity

Information to Provide

When contacting support, include:

• Agent version (getVersion())
• iOS version and device type
• Xcode version
• Error messages and logs
• Configuration used
• Steps to reproduce the issue

Support Resources

• Documentation: This troubleshooting guide
• Console Logs: Enable printLog: true
• Network Monitoring: Use Xcode Network Inspector
• Community: NetFUNNEL developer community

---