Skip to main content
Version: 4.6.1

Quickstart

Get your NetFUNNEL 4 iOS Agent up and running in 5-10 minutes with this quickstart guide.

What you can do with this guide​

  • Code-based Integration: Apply traffic control by calling NetFUNNEL functions in your iOS code
  • Basic Control: Limit entry speed for ViewControllers, button taps, and API calls
  • Section Control: Control concurrent users within specific application sections
Choose Your Control Type

Not sure which control type to use? Check out the Integration Methods Overview to compare Basic Control and Section Control approaches and find the best fit for your use case.

Prerequisites​

  • NetFUNNEL console access
  • Xcode environment
  • Basic understanding of iOS development (Swift/Objective-C)
  • iOS 12.0 or later
Practice Projects Available

Need a basic project to practice with? Check out our Sample Projects which include an iOS Application (Single ViewController) template ready for NetFUNNEL SDK integration practice.

Step 1: Install SDK & Initialize Agent​

1.1 Download SDK from NetFUNNEL Console​

  1. Log in to your NetFUNNEL console
  2. Navigate to Agent → Mobile Agent → iOS
  3. Download the ZIP file: netfunnel-ios-agent-4.3.2-onprem.zip
  4. Extract the ZIP file to get the folder structure: 
    netfunnel-ios-agent-4.3.2-onprem/
    ├── netfunnel-ios-agent-debug/
    │   └── netfunnel_ios.xcframework
    └── netfunnel-ios-agent-release/
        └── netfunnel_ios.xcframework

1.2 Add Framework to Project​

1. Create Frameworks folder:

  • Create Frameworks folder at your project root
  • Copy netfunnel-ios-agent-debug/netfunnel_ios.xcframework to Frameworks folder (for development)

2. Register Framework in Xcode:

  • Go to Project ▸ General ▸ Frameworks, Libraries, and Embedded Content
  • Click + and select Add Files…
  • Select the netfunnel_ios.xcframework file
  • Confirm the framework appears in the list

3. Add internet permission to Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

1.3 Initialize Agent​

Get initialization code from NetFUNNEL console:

  1. Go to Agent → Mobile Agent → iOS
  2. Copy the initialization code with your actual server URLs

Add to your AppDelegate:

Critical: Must Initialize First

Initialize in application(_:didFinishLaunchingWithOptions:) before calling super. Missing this step = bypass mode (no protection).

import UIKit
import Netfunnel_iOS

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

Replace the placeholder {{CLIENT_ID}} with your actual client ID from the NetFUNNEL console.

Step 2: Choose Your Control Type​

Option A: Basic Control (5 minutes)​

Best for: ViewController entry, button taps, API calls

  1. Add the SDK to your project (see Installation & Initialization)
  2. Create a segment in NetFUNNEL console:
    • Go to Projects → Segments → Create Segment
    • Choose Basic Control
    • Set Limited Inflow to 0 (for testing)
  3. Add this code to your ViewController:
import UIKit
import Netfunnel_iOS

class ViewController: UIViewController, NetfunnelDelegate {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Start NetFUNNEL when user enters the view
        Netfunnel.shared.nfStart(projectKey: "{{PROJECT_KEY}}", segmentKey: "{{SEGMENT_KEY}}")
    }
    
    // MARK: - NetfunnelDelegate Methods
    
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // User can proceed - run your original logic
        DispatchQueue.main.async {
            self.setupUI()
        }
    }
    
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // System error - proceed with original logic for service availability
        DispatchQueue.main.async {
            self.setupUI()
        }
    }
    
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // Network error - log only, rely on network recovery mode
        print("NetFUNNEL Network error: \(message)")
    }
    
    func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // User is blocked - show appropriate message
        DispatchQueue.main.async {
            let alert = UIAlertController(title: "Access Blocked", message: message, preferredStyle: .alert)
            alert.addAction(UIAlertAction(title: "OK", style: .default))
            self.present(alert, animated: true)
        }
    }
    
    func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // User closed waiting room - handle appropriately
        print("NetFUNNEL User closed waiting room: \(message)")
    }
    
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        print("NetFUNNEL Continue: \(message), waitTime: \(waitTime)")
    }
    
    func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        print("NetFUNNEL Key returned successfully")
    }
    
    // Return key when user leaves
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        Netfunnel.shared.nfStop(projectKey: "{{PROJECT_KEY}}", segmentKey: "{{SEGMENT_KEY}}")
    }
    
    private func setupUI() {
        // Your original UI setup logic
    }
}

Result: A waiting room appears when users enter the ViewController.

Option B: Section Control (10 minutes)​

Best for: Multi-step processes, maintaining concurrent user limits

  1. Add the SDK to your project (same as Option A)
  2. Create a segment in NetFUNNEL console (choose Section Control)
  3. Add this code to your checkout/payment flow:
import UIKit
import Netfunnel_iOS

class CheckoutViewController: UIViewController, NetfunnelDelegate {
    
    // Start section (e.g., checkout process)
    func startCheckout() {
        Netfunnel.shared.nfStartSection(projectKey: "{{PROJECT_KEY}}", segmentKey: "{{SEGMENT_KEY}}")
    }
    
    // MARK: - NetfunnelDelegate Methods
    
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // User entered the section
        DispatchQueue.main.async {
            self.showCheckoutForm()
        }
    }
    
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // System error - proceed with original logic for service availability
        DispatchQueue.main.async {
            self.showCheckoutForm()
        }
    }
    
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // Network error - log only, rely on network recovery mode
        print("NetFUNNEL Network error: \(message)")
    }
    
    func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // User is blocked - show appropriate message
        DispatchQueue.main.async {
            let alert = UIAlertController(title: "Access Blocked", message: message, preferredStyle: .alert)
            alert.addAction(UIAlertAction(title: "OK", style: .default))
            self.present(alert, animated: true)
        }
    }
    
    func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // User closed waiting room - handle appropriately
        print("NetFUNNEL User closed waiting room: \(message)")
    }
    
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        print("NetFUNNEL Continue: \(message), waitTime: \(waitTime)")
    }
    
    func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        print("NetFUNNEL Section key returned successfully")
    }
    
    // End section (e.g., after payment completion)
    func completeCheckout() {
        // Your checkout completion logic
        processPayment()
        
        // Return key after successful completion
        Netfunnel.shared.nfStopSection(projectKey: "{{PROJECT_KEY}}", segmentKey: "{{SEGMENT_KEY}}")
    }
    
    private func showCheckoutForm() {
        // Your checkout form setup logic
    }
    
    private func processPayment() {
        // Your payment processing logic
    }
}

Result: Users wait in queue before entering the checkout section, maintaining controlled concurrency.

Step 3: Test It Works​

For Basic Control:​

  1. Set Limited Inflow to 0 in your segment (waiting room should appear)
  2. Check the waiting room displays correctly (shows estimated wait time)
  3. Set Limited Inflow to 1 (should enter immediately)
  4. Verify key return in logs or network monitoring

For Section Control:​

  1. Set Limited Inflow to 0 in your segment (waiting room should appear)
  2. Check the waiting room displays correctly (no estimated wait time shown)
  3. Set Limited Inflow to 1 (should enter section immediately)
  4. Navigate through section (Section1 → Section2 → End)
  5. Verify key timeout extension in logs (look for 5003 requests)
  6. Verify key return when section completes

Need Help?​

  • Troubleshooting: Common issues and solutions
  • Check the iOS logs for NetFUNNEL messages (enable printLog = true)
  • Verify your project/segment keys match the console exactly