Troubleshooting & FAQ

Common issues, solutions, and frequently asked questions for NetFUNNEL Android Agent integration.

---

Table of Contents

• Installation Issues
• Initialization Issues
• Function Call Errors
• Network & Connection Issues
• Waiting Room Issues
• Key Management Issues
• Configuration Issues
• Build & Environment Issues
• FAQ

---

Installation Issues

AAR File Not Loading

Symptoms:

• Build errors related to NetFUNNEL classes
• "Cannot resolve symbol" errors
• AAR file not found errors

Solutions:

1. Check AAR file location: Ensure the .aar file is in app/libs/ directory
2. Verify build.gradle configuration: Check dependencies are correctly added
3. Clean and rebuild: Clean project and rebuild
4. Check file permissions: Ensure AAR file is readable

Kotlin DSL (build.gradle.kts)

// Verify in build.gradle.kts
dependencies {
    implementation(files("libs/netfunnel-android-agent-release-{{latest}}.aar"))
}

Groovy DSL (build.gradle)

// Verify in build.gradle
dependencies {
    implementation files('libs/netfunnel-android-agent-release-{{latest}}.aar')
}

External Dependencies Not Resolved

Symptoms:

• Ktor or Kotlinx Serialization not found
• Build errors for external libraries
• Missing dependency warnings

Solutions:

1. Add required dependencies: Ensure all external dependencies are added
2. Check versions: Use compatible versions
3. Sync project: Sync project with Gradle files

Kotlin DSL (build.gradle.kts)

// Add required dependencies
dependencies {
    val ktorVersion = "2.3.12"
    val serializationVersion = "1.6.3"
    
    implementation("io.ktor:ktor-client-core:$ktorVersion")
    implementation("io.ktor:ktor-client-okhttp:$ktorVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-gson:$ktorVersion")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion")
}

Groovy DSL (build.gradle)

// Add required dependencies
dependencies {
    def ktorVersion = "2.3.12"
    def serializationVersion = "1.6.3"
    
    implementation "io.ktor:ktor-client-core:$ktorVersion"
    implementation "io.ktor:ktor-client-okhttp:$ktorVersion"
    implementation "io.ktor:ktor-client-content-negotiation:$ktorVersion"
    implementation "io.ktor:ktor-serialization-gson:$ktorVersion"
    implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion"
}

Build Configuration Issues

Symptoms:

• Compilation errors
• Incompatible API level errors
• Java version compatibility issues

Solutions:

1. Check API levels: Ensure minSdk >= 22 and targetSdk >= 22
2. Verify Java version: Use Java 1.8 or higher
3. Check build features: Enable viewBinding = true

Kotlin DSL (build.gradle.kts)

// Verify build.gradle.kts configuration
android {
    compileSdk = 34
    
    defaultConfig {
        minSdk = 22
        targetSdk = 34
    }
    
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    
    kotlinOptions {
        jvmTarget = "1.8"
    }
    
    buildFeatures {
        viewBinding = true
    }
}

Groovy DSL (build.gradle)

// Verify build.gradle configuration
android {
    compileSdk 34
    
    defaultConfig {
        minSdk 22
        targetSdk 34
    }
    
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    
    kotlinOptions {
        jvmTarget = '1.8'
    }
    
    buildFeatures {
        viewBinding true
    }
}

---

Initialization Issues

Agent Not Initializing

Symptoms:

• No NetFUNNEL logs in Logcat
• Functions not available
• Bypass mode behavior

Solutions:

1. Check initialization location: Ensure initialization is in Application.onCreate()
2. Verify parameters: Check all required parameters are provided
3. Check client ID: Ensure clientId is correct and accessible
4. Enable logging: Set printLog = true for debugging

Kotlin

// Correct initialization
class SampleApplication : Application() {
    override fun onCreate() {
        Netfunnel.initialize(
            clientId = "{{CLIENT_ID}}",
            printLog = true // Enable for debugging
        )
        
        super.onCreate()
    }
}

Java

// Correct initialization
public class SampleApplication extends Application {
    @Override
    public void onCreate() {
        Netfunnel.INSTANCE.initialize(
            "{{CLIENT_ID}}"
        );
        
        super.onCreate();
    }
}

Manifest Registration Missing

Symptoms:

• Application class not being called
• Initialization not happening
• App crashes on startup

Solutions:

1. Register Application class: Add to AndroidManifest.xml
2. Check class name: Ensure correct class name is used
3. Verify package: Check package name matches

<!-- AndroidManifest.xml -->
<application
    android:name=".SampleApplication"
    android:allowBackup="true">
    <!-- Your activities -->
</application>

Bypass Mode (No Waiting Room)

Symptoms:

• Users access app directly without waiting room
• No NetFUNNEL traffic control
• Functions work but no protection

Solutions:

1. Check client ID: Ensure clientId is correct and accessible
2. Verify segment status: Check segment is activated in console
3. Check Limited Inflow: Verify Limited Inflow is not set to unlimited
4. Enable logging: Check logs for initialization errors

---

Function Call Errors

"Netfunnel is not initialized" Error

Symptoms:

• IllegalStateException: Netfunnel is not initialized
• Functions throw exceptions
• App crashes when calling NetFUNNEL functions

Solutions:

1. Check initialization: Ensure Netfunnel.initialize() is called first
2. Check timing: Don't call functions before initialization
3. Verify Application class: Ensure Application class is properly registered

Kotlin

// Check if initialized before calling functions
if (Netfunnel.isInitialized()) {
    Netfunnel.nfStart(projectKey, segmentKey, callback, this)
} else {
    Log.e("NetFUNNEL", "Agent not initialized")
    // Handle error or initialize
}

Java

// Check if initialized before calling functions
if (Netfunnel.INSTANCE.isInitialized()) {
    Netfunnel.INSTANCE.nfStart(projectKey, segmentKey, callback, this);
} else {
    Log.e("NetFUNNEL", "Agent not initialized");
    // Handle error or initialize
}

Callback Not Executing

Symptoms:

• nfStart called but callback never fires
• No response received
• App hangs waiting for callback

Solutions:

1. Check network: Verify network requests to NetFUNNEL server
2. Enable logging: Set printLog = true for debugging
3. Check segment status: Ensure segment is not in Block state
4. Verify callback implementation: Ensure callback is properly implemented

Kotlin

// Enable logging for debugging
Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    printLog = true // Enable logging
)

// Check logs in Logcat for NetFUNNEL messages

Java

// Enable logging for debugging
Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}"
);

// Check logs in Logcat for NetFUNNEL messages

Activity Context Issues

Symptoms:

• IllegalArgumentException: Activity cannot be null
• Context-related errors
• App crashes when calling functions

Solutions:

1. Check activity context: Ensure valid Activity is passed
2. Check timing: Don't call functions after Activity is destroyed
3. Use proper lifecycle: Call functions in appropriate lifecycle methods

Kotlin

// Correct usage
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    
    // Safe to call here
    Netfunnel.nfStart(projectKey, segmentKey, callback, this)
}

// Avoid calling after onDestroy
override fun onDestroy() {
    super.onDestroy()
    // Don't call NetFUNNEL functions here
}

Java

// Correct usage
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    
    // Safe to call here
    Netfunnel.INSTANCE.nfStart(projectKey, segmentKey, callback, this);
}

// Avoid calling after onDestroy
@Override
protected void onDestroy() {
    super.onDestroy();
    // Don't call NetFUNNEL functions here
}

---

Network & Connection Issues

Network Timeout Errors

Symptoms:

• NetworkError with status code 1002
• Requests timing out
• Callbacks not received

Solutions:

1. Increase timeout: Set networkTimeout to higher value (max 10000ms)
2. Retry configuration: Increase retryCount
3. Network recovery: Enable useNetworkRecoveryMode = true

Kotlin

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    networkTimeout = 5000, // Increase timeout
    retryCount = 3, // Increase retries
    errorBypass = false
)

Java

Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}",
    5000, // Increase timeout
    3, // Increase retries
    false,
    false
);

Network Not Connected Errors

Symptoms:

• NetworkError with status code 1001
• No internet connectivity
• Network permission issues

Solutions:

1. Check connectivity: Verify internet connection
2. Check permissions: Ensure INTERNET permission is granted
3. Check firewall: Ensure NetFUNNEL domains are not blocked
4. Implement error handling: Handle NetworkError appropriately

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />

Kotlin

// Handle network errors
private val callback = object : NetfunnelCallback() {
    override fun onNetworkError(statusCode: Int, message: String) {
        when (statusCode) {
            1001 -> {
                // Network not connected
                showNetworkErrorDialog()
            }
            1002 -> {
                // Network timeout
                showTimeoutDialog()
            }
        }
    }
}

Java

// Handle network errors
private final NetfunnelCallback callback = new NetfunnelCallback() {
    @Override
    public void onNetworkError(int statusCode, @NonNull String message) {
        switch (statusCode) {
            case 1001:
                // Network not connected
                showNetworkErrorDialog();
                break;
            case 1002:
                // Network timeout
                showTimeoutDialog();
                break;
        }
    }
};

Server Communication Issues

Symptoms:

• No response from NetFUNNEL server
• HTTP errors in logs
• Authentication failures

Solutions:

1. Check client configuration: Verify clientId is correct
2. Check authentication: Ensure valid clientId
3. Check network: Verify network connectivity to NetFUNNEL servers
4. Check logs: Enable logging to see detailed error messages

---

Waiting Room Issues

Waiting Room Not Displaying

Symptoms:

• No waiting room appears
• Users proceed directly
• No visual feedback

Solutions:

1. Check Limited Inflow: Set to 0 for testing
2. Check segment activation: Ensure segment is activated
3. Check template settings: Verify useNetfunnelTemplate = true
4. Check callback implementation: Ensure callbacks are properly implemented

Kotlin

// Enable logging for debugging
Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    printLog = true // Enable logging
)

Java

// Enable logging for debugging
Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}"
);

Waiting Room Stuck (Never Ends)

Symptoms:

• Waiting room appears but never allows entry
• Infinite waiting
• No progress indication

Solutions:

1. Check Limited Inflow: Increase Limited Inflow value
2. Check segment status: Ensure segment is not in Block state
3. Check network: Verify network connectivity
4. Check server status: Verify NetFUNNEL server status

Custom Template Issues

Symptoms:

• Custom waiting room not updating
• onContinue callback not called
• UI not reflecting queue status

Solutions:

1. Disable template: Set useNetfunnelTemplate = false
2. Implement onContinue: Handle onContinue callback
3. Check callback implementation: Ensure proper callback setup

Kotlin

// Basic configuration
Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    errorBypass = false
)

// Implement onContinue callback
private val callback = object : NetfunnelCallback() {
    override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        // Update your custom waiting room UI
        updateCustomWaitingRoom(aheadWait, behindWait, waitTime, progressRate)
    }
}

Java

// Basic configuration
Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}"
);

// Implement onContinue callback
private final NetfunnelCallback callback = new NetfunnelCallback() {
    @Override
    public void onContinue(int statusCode, @NonNull String message, int aheadWait, int behindWait, @NonNull String waitTime, int progressRate) {
        // Update your custom waiting room UI
        updateCustomWaitingRoom(aheadWait, behindWait, waitTime, progressRate);
    }
};

---

Key Management Issues

Key Not Returned

Symptoms:

• Next users remain waiting indefinitely
• Queue doesn't progress
• Server errors about key management

Solutions:

1. Always call nfStop: Ensure nfStop/nfStopSection is called
2. Error handling: Return key even in error scenarios
3. Check timing: Don't call stop before start completes
4. Check key matching: Use identical keys for start/stop

Kotlin

// Always return key
private val callback = object : NetfunnelCallback() {
    override fun onSuccess(statusCode: Int, message: String) {
        try {
            performAction()
        } finally {
            // Always return key
            Netfunnel.nfStop(projectKey, segmentKey, completeCallback)
        }
    }
    
    override fun onError(statusCode: Int, message: String) {
        // Return key even on error
        Netfunnel.nfStop(projectKey, segmentKey, completeCallback)
    }
}

Java

// Always return key
private final NetfunnelCallback callback = new NetfunnelCallback() {
    @Override
    public void onSuccess(int statusCode, @NonNull String message) {
        try {
            performAction();
        } finally {
            // Always return key
            Netfunnel.INSTANCE.nfStop(projectKey, segmentKey, completeCallback);
        }
    }
    
    @Override
    public void onError(int statusCode, @NonNull String message) {
        // Return key even on error
        Netfunnel.INSTANCE.nfStop(projectKey, segmentKey, completeCallback);
    }
};

Key Mismatch Errors

Symptoms:

• Server errors about invalid keys
• Key not found errors
• Function calls fail

Solutions:

1. Key consistency: Use identical keys for start/stop functions
2. Key scope: Don't reuse keys across different actions
3. Timing: Don't call stop before start completes
4. Check console: Verify keys match console exactly

Kotlin

// Use consistent keys
val projectKey = "service_1"
val segmentKey = "segKey_123"

// Start
Netfunnel.nfStart(projectKey, segmentKey, callback, this)

// Stop (must use same keys)
Netfunnel.nfStop(projectKey, segmentKey, completeCallback)

Java

// Use consistent keys
String projectKey = "service_1";
String segmentKey = "segKey_123";

// Start
Netfunnel.INSTANCE.nfStart(projectKey, segmentKey, callback, this);

// Stop (must use same keys)
Netfunnel.INSTANCE.nfStop(projectKey, segmentKey, completeCallback);

---

Configuration Issues

Wrong Project/Segment Keys

Symptoms:

• Functions called but no effect
• Wrong segment behavior
• Server errors

Solutions:

1. Console verification: Double-check keys in NetFUNNEL console
2. Copy exactly: Copy keys exactly as shown in console
3. Environment: Ensure using correct environment (prod vs staging)
4. Check segment type: Ensure using correct segment type (Basic vs Section)

Parameter Validation Errors

Symptoms:

• Initialization fails
• IllegalArgumentException errors
• Invalid parameter warnings

Solutions:

1. Check parameter ranges: Ensure values are within allowed ranges
2. Check required parameters: Ensure all required parameters are provided
3. Check parameter types: Ensure correct data types are used

Kotlin

// Valid parameter ranges
Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}", // Required
    networkTimeout = 5000, // Must be 100-10000
    retryCount = 3, // Must be 0-10
    printLog = true, // Boolean
    errorBypass = false // Boolean
)

Java

// Valid parameter ranges
Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}", // Required
    5000, // Must be 100-10000
    3, // Must be 0-10
    true, // Boolean
    false // Boolean
);

---

Build & Environment Issues

ProGuard/R8 Issues

Symptoms:

• App works in debug but not release
• Class not found errors
• Method not found errors
• NetFUNNEL functions not working in release builds

Solutions:

1. Add ProGuard rules: Add NetFUNNEL classes to ProGuard rules
2. Check R8 configuration: Ensure R8 doesn't obfuscate NetFUNNEL classes
3. Test release build: Test with release build configuration

Required ProGuard Rules:

Add these rules to your app/proguard-rules.pro file:

# NetFUNNEL Android Agent - Protect main packages and classes
-keep class com.nf4.** { *; }

# NetFUNNEL Android Agent - Keep reflection-related classes and members
-keepclassmembers class com.nf4.** { *; }

Why This Is Required:

• Release builds use code shrinking, obfuscation, and optimization
• NetFUNNEL Android Agent uses reflection and dynamic class loading
• Without these rules, NetFUNNEL classes get obfuscated and functionality breaks
• This configuration is mandatory for production releases

Testing:

1. Build release APK/Bundle
2. Install on device
3. Test NetFUNNEL functionality
4. Check Logcat for any class loading errors

Android Version Compatibility

Symptoms:

• App crashes on older Android versions
• API level compatibility errors
• Feature not available errors

Solutions:

1. Check minSdk: Ensure minSdk >= 22
2. Check targetSdk: Ensure targetSdk >= 22
3. Test on devices: Test on actual devices with different Android versions
4. Check API usage: Ensure using compatible APIs

Development vs Production

Symptoms:

• Works in development but not production
• Different behavior between environments
• Configuration differences

Solutions:

1. Environment configuration: Use correct configuration for each environment
2. Console setup: Set up separate segments for dev/prod
3. Build configuration: Ensure proper build configuration
4. Testing: Test both development and production builds

---

FAQ

Can I use both Basic Control and Section Control in the same app?

A: Yes, you can use both methods in the same application:

Kotlin

// Basic Control for login
fun handleLogin() {
    Netfunnel.nfStart("login_project", "login_segment", loginCallback, this)
}

// Section Control for checkout
fun startCheckout() {
    Netfunnel.nfStartSection("checkout_project", "checkout_segment", checkoutCallback, this)
}

Java

// Basic Control for login
public void handleLogin() {
    Netfunnel.INSTANCE.nfStart("login_project", "login_segment", loginCallback, this);
}

// Section Control for checkout
public void startCheckout() {
    Netfunnel.INSTANCE.nfStartSection("checkout_project", "checkout_segment", checkoutCallback, this);
}

How should I handle NetworkError?

A: Notify the user and either retry or proceed with original logic:

Kotlin

private val callback = object : NetfunnelCallback() {
    override fun onNetworkError(statusCode: Int, message: String) {
        when (statusCode) {
            1001 -> {
                // Network not connected
                showNetworkErrorDialog()
            }
            1002 -> {
                // Network timeout - retry
                retryWithDelay()
            }
        }
    }
}

private fun retryWithDelay() {
    Handler(Looper.getMainLooper()).postDelayed({
        Netfunnel.nfStart(projectKey, segmentKey, callback, this)
    }, 2000)
}

Java

private final NetfunnelCallback callback = new NetfunnelCallback() {
    @Override
    public void onNetworkError(int statusCode, @NonNull String message) {
        switch (statusCode) {
            case 1001:
                // Network not connected
                showNetworkErrorDialog();
                break;
            case 1002:
                // Network timeout - retry
                retryWithDelay();
                break;
        }
    }
};

private void retryWithDelay() {
    new Handler(Looper.getMainLooper()).postDelayed(() -> {
        Netfunnel.INSTANCE.nfStart(projectKey, segmentKey, callback, this);
    }, 2000);
}

What if I forget to return the key?

A: The key may be auto-returned by server timeout, but this can cause bottlenecks. Always return explicitly:

Kotlin

// Good: Always return key
private val callback = object : NetfunnelCallback() {
    override fun onSuccess(statusCode: Int, message: String) {
        performAction()
            .onSuccess {
                Netfunnel.nfStop(projectKey, segmentKey, completeCallback)
            }
            .onFailure {
                Netfunnel.nfStop(projectKey, segmentKey, completeCallback) // Even on error
            }
    }
}

Java

// Good: Always return key
private final NetfunnelCallback callback = new NetfunnelCallback() {
    @Override
    public void onSuccess(int statusCode, @NonNull String message) {
        performAction()
            .onSuccess(() -> {
                Netfunnel.INSTANCE.nfStop(projectKey, segmentKey, completeCallback);
            })
            .onFailure(() -> {
                Netfunnel.INSTANCE.nfStop(projectKey, segmentKey, completeCallback); // Even on error
            });
    }
};

Can I initialize NetFUNNEL multiple times?

A: No, NetFUNNEL should be initialized only once in your Application class. Multiple initializations may cause unexpected behavior.

How do I debug NetFUNNEL integration?

A: Enable logging and check the logs:

Kotlin

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

Java

Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}"
);

Then check Logcat for NetFUNNEL log messages.

What's the difference between Basic Control and Section Control?

A:

• Basic Control: Limits entry speed (how fast users can enter)
• Section Control: Maintains fixed concurrent user count (how many users can be active simultaneously)

Use Basic Control for simple entry limiting, Section Control for maintaining specific concurrency levels.

Can I use NetFUNNEL in a Fragment?

A: Yes, but you need to pass the Activity context:

Kotlin

class MyFragment : Fragment() {
    fun startNetFUNNEL() {
        activity?.let { activity ->
            Netfunnel.nfStart(projectKey, segmentKey, callback, activity)
        }
    }
}

Java

public class MyFragment extends Fragment {
    public void startNetFUNNEL() {
        Activity activity = getActivity();
        if (activity != null) {
            Netfunnel.INSTANCE.nfStart(projectKey, segmentKey, callback, activity);
        }
    }
}

---

Getting Help

If you're still experiencing issues:

1. Check logs: Enable printLog = true and check Logcat
2. Verify configuration: Double-check all settings in NetFUNNEL console
3. Test with simple setup: Start with basic configuration and add complexity gradually
4. Contact support: Reach out to NetFUNNEL support with specific error details

---

Related Documentation

• Quickstart: Begin quickly
• Installation & Initialization: Basic setup guide
• Integration Methods Overview: Compare Basic Control vs Section Control approaches
• Basic Control Integration: Implementation guide
• Section Control Integration: Implementation guide
• API Reference: Complete function specifications
• Configuration Options: All available options