Skip to main content
Version: 4.6.1

Installation & Initialization

This guide covers the essential setup steps for integrating the NetFUNNEL iOS Agent into your application.

Prerequisites​

System Requirements​

ComponentVersionNotes
iOS12+Covers 99% of active iOS devices
StoryboardObjective-C, SwiftFor UIKit-based development
SwiftUICompatibleFor SwiftUI-based development

Step 1: Download SDK​

1.1 Download from NetFUNNEL Console​

iOS Agent SDK Download placement

  1. Log in to your NetFUNNEL console
  2. Navigate to Agent → Mobile Agent → iOS
  3. Click "Traffic Control Installation File" button
  4. Download the ZIP file: netfunnel-ios-agent-{{version}}.zip

1.2 Extract Files​

  1. Extract the ZIP file to get: 
    netfunnel-ios-agent-{{version}}/
    ├── netfunnel-ios-agent-debug/
    │   └── netfunnel_ios.xcframework    // (for development)
    └── netfunnel-ios-agent-release/
        └── netfunnel_ios.xcframework    // (for production)
Build Type
  • Development: Use debug xcframework
  • Production: Use release xcframework

Step 2: Add Dependencies​

2.1 Add Framework​

  1. Create Frameworks folder at your project root (same level as .xcodeproj file)

  2. Copy the appropriate xcframework to Frameworks/:

    Project structure:

    your-project/
    ├── YourProject/
    │   ├── AppDelegate.swift
    │   └── ...
    ├── Frameworks/
    │   └── netfunnel_ios.xcframework   // (from debug or release folder)
    └── YourProject.xcodeproj

  3. Register framework in Xcode:

    • Select your project in Project Navigator
    • Go to General → Frameworks, Libraries, and Embedded Content
    • Click + → Add Files… → Select netfunnel_ios.xcframework
    • Click Add
    • Set Embed to Embed & Sign

iOS Agent Framework Import Result

Framework Registration

Make sure the framework appears without question marks (?). If you see a question mark, right-click → Source Control → Add netfunnel_ios.xcframework

2.2 Configure App Transport Security (if needed)​

Only required if your NetFUNNEL server uses HTTP instead of HTTPS.

For projects where Info.plist is hidden

  1. Select your app Target in Project Navigator
  2. Go to the Info tab
  3. Right-click any existing row → Add Row
  4. Enter "App Transport Security Settings" → Set as Dictionary
  5. Expand App Transport Security Settings → Add Row
  6. Enter "Allow Arbitrary Loads" → Set to "YES" (Boolean)
Production Safety

Use NSExceptionDomains with specific server domains for production builds to avoid App Store review rejection.

2.3 Verify Setup​

  1. Clean project: Product → Clean Build Folder (⌘+Shift+K)
  2. Build project: Product → Build (⌘+B)

Step 3: Initialize Agent​

3.1 Create NetfunnelHandler Class​

Before initializing NetFUNNEL, create a dedicated handler class for delegate methods:

  1. Create NetfunnelHandler files:
  • Right-click on your project in Xcode
  • Select New File → Swift File
  • Name it NetfunnelHandler
  • Add to project target when prompted
File Registration Required

Important: After creating NetfunnelHandler.swift, you must register it with your project target. Xcode will prompt you to add it to the target - make sure to check the box for your app target.

File Location

Place NetfunnelHandler.swift in your main app folder alongside AppDelegate.swift.

  1. Add the handler implementation:
//  NetfunnelHandler.swift
import Foundation
import Netfunnel_iOS

class NetfunnelHandler: NSObject, NetfunnelDelegate {
    static let shared = NetfunnelHandler()
    
    var onSuccess: ((String, String, Int, String) -> Void)?
    var onError: ((String, String, Int, String) -> Void)?
    var onNetworkError: ((String, String, Int, String) -> Void)?
    var onContinue: ((String, String, Int, String, Int, Int, String, Int) -> Void)?
    var onBlock: ((String, String, Int, String) -> Void)?
    var onClose: ((String, String, Int, String) -> Void)?
    var onComplete: ((String, String, Int, String) -> Void)?
    
    private override init() {
        super.init()
    }
    
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onSuccess?(projectKey, segmentKey, statusCode, message)
    }
    
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onError?(projectKey, segmentKey, statusCode, message)
    }
    
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onNetworkError?(projectKey, segmentKey, statusCode, message)
    }
    
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String,
                    aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        onContinue?(projectKey, segmentKey, statusCode, message, aheadWait, behindWait, waitTime, progressRate)
    }
    
    func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onBlock?(projectKey, segmentKey, statusCode, message)
    }
    
    func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onClose?(projectKey, segmentKey, statusCode, message)
    }
    
    func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onComplete?(projectKey, segmentKey, statusCode, message)
    }
}

3.2 Get Initialization Code from NetFUNNEL Console​

  1. Log in to your NetFUNNEL console
  2. Navigate to Agent → Mobile Agent → iOS
  3. Copy the initialization code with your actual server URLs

iOS Agent Initialization Code from NetFUNNEL Console

3.3 Initialize in AppDelegate​

Critical: Must Initialize First

Initialize in application(_:didFinishLaunchingWithOptions:) at the beginning of the method. Missing this step = bypass mode (no protection).

3.3.1 Check Your Project Type​

  • UIKit Projects: ✅ You already have AppDelegate - Skip to 3.3.3
  • SwiftUI Projects: ⚠️ You need to create AppDelegate - Follow 3.3.2

3.3.2 Create AppDelegate (SwiftUI Only)​

Create AppDelegate File

  • Right-click on your project in Xcode
  • Select New File → Swift File
  • Name it AppDelegate

Connect to SwiftUI

Open your main App file (e.g., YourAppNameApp.swift) and add:

// YourAppNameApp.swift
import SwiftUI

@main
struct YourAppNameApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

3.3.3 Add Initialization Code​

Copy the initialization code from NetFUNNEL Console and add it to your AppDelegate file:

  1. Copy from Console: Use the initialization code you copied from NetFUNNEL Console (3.2)
  2. Add to AppDelegate: Paste it into the application(_:didFinishLaunchingWithOptions:) method

Open AppDelegate.swift and add the initialization code to the application(_:didFinishLaunchingWithOptions:) method:

// AppDelegate.swift
import UIKit
import Netfunnel_iOS

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        // Paste your NetFUNNEL Console initialization code here
        Netfunnel.initialize(
            clientId: "{{CLIENT_ID}}",
            delegate: self // Set the delegate to a specified delegate object or 'self'.
        )
        
        return true
    }
}

3.3.4 Modify Initialization Parameters​

Important changes you need to make:

  1. Change delegate parameter:

    • Console code: delegate: self (Swift) or delegate:self (Objective-C)
    • Change to: delegate: NetfunnelHandler.shared (Swift) or delegate:[NetfunnelHandler sharedInstance] (Objective-C)

  2. Enable debug logging for testing:

    • Change: printLog: false → printLog: true
    • Purpose: See NetFUNNEL logs in Xcode Console for debugging

Modified AppDelegate code:

// AppDelegate.swift - Modified version
import UIKit
import Netfunnel_iOS

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        Netfunnel.initialize(
            clientId: "{{CLIENT_ID}}",
            delegate: NetfunnelHandler.shared  // Changed from 'self'
        )
        
        return true
    }
}
Production Settings

Remember to set printLog: false in production builds for better performance and security.

Use Real Client ID

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

Advanced: Exception Handling​

For production apps, add try-catch error handling and set printLog: false:

import UIKit
import Netfunnel_iOS

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        do {
            try Netfunnel.initialize(
                clientId: "{{CLIENT_ID}}",
                delegate: NetfunnelHandler.shared
            )
        } catch {
            print("NetFUNNEL initialization failed: \(error)")
            // Handle error: show error screen or exit app
        }
        
        return true
    }
}

Required Parameters​

ParameterTypeRequiredDescription
clientIdStringYesClient ID from NetFUNNEL console
delegateNetfunnelDelegateYesDelegate object implementing protocol
Bypass Mode

Missing clientId = bypass mode (no waiting room protection)

More Configuration Options

For additional initialization parameters like networkTimeout, retryCount, printLog, and more, see the Configuration Options Reference.

Step 4: Build and Verify Installation​

Now that you've completed the SDK setup and initialization, let's build your project and verify that NetFUNNEL is working correctly.

4.1 Build Your Project​

Sync and Build​

  1. Clean Project

    • Go to Product → Clean Build Folder
    • Wait for cleaning to complete

  2. Build Project

    • Press ⌘+B or go to Product → Build
    • Monitor the Issue Navigator for any errors

Verify Build Success​

  1. Check Build Output

    • Ensure no compilation errors in the Issue Navigator
    • Look for successful framework linking messages
    • Verify NetFUNNEL framework is properly included

  2. Verify Dependencies

    • In the Project Navigator, expand your project
    • Confirm you see netfunnel_ios.xcframework listed
    • Check that the framework appears without question marks

4.2 Test NetFUNNEL Initialization​

Enable Debug Logging​

To verify NetFUNNEL is initializing correctly, temporarily enable debug logging in your AppDelegate:

Disable Debug Logging

Remember to set printLog = false in production builds for better performance and security.

//  AppDelegate.swift
Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: NetfunnelHandler.shared
)

Monitor Console Output​

  1. Open Console

    • Go to View → Debug Area → Activate Console (⌘+Shift+Y)
    • Or click the Console tab in the bottom panel

  2. Filter NetFUNNEL Logs

    • In the console filter field, enter NetFUNNEL to filter by NetFUNNEL logs
    • This will show only NetFUNNEL-related log messages

  3. Run Your App

    • Run your app on a device or simulator
    • Look for initialization success messages in Console:
    [NF4] Initialization successful. NetFUNNEL Version: {{version}}

Troubleshooting​

If you encounter any issues during installation or initialization, please refer to the comprehensive Troubleshooting & FAQ guide for detailed solutions to common problems including:

  • Installation Issues: Framework loading, project configuration, build settings
  • Initialization Issues: Agent not initializing, delegate registration, bypass mode
  • Function Call Errors: Initialization errors, callback issues, context problems
  • Network & Connection Issues: Timeout errors, connectivity problems, server communication
  • Build & Environment Issues: Xcode configuration, iOS version compatibility

For immediate help with common issues:

  1. Check Console: Filter by NetFUNNEL to see detailed logs
  2. Verify configuration: Double-check all settings match your NetFUNNEL console
  3. Test with simple setup: Start with basic configuration first
  4. Verify client ID: Ensure your client ID matches the one from NetFUNNEL console