Skip to main content
Version: 4.6.1

Initialization Option Reference

Complete reference for all NetFUNNEL Android Agent configuration options and parameters.

Table of Contents​

Complete Initialization Example​

Here's a complete example showing all available configuration options:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    networkTimeout = 3000,
    retryCount = 0,
    printLog = false,
    errorBypass = false,
    useNetfunnelTemplate = true,
    userId = "user_67890",
    useNetworkRecoveryMode = true,
    statusBarStyle = null
)

Required Parameters​

These parameters are mandatory for the agent to function properly.

ParameterTypeDescriptionRequiredExample
clientIdStringNetFUNNEL client IDYes"{{CLIENT_ID}}"
Bypass Mode

If clientId is missing, the agent runs in bypass mode, allowing direct access without a waiting room.

Network Settings​

Control network behavior and timeouts for NetFUNNEL server communications.

ParameterTypeRequiredDefaultRange
networkTimeoutLongOptional3000100–10000
retryCountIntOptional00–10
useNetworkRecoveryModeBooleanOptionalfalsetrue/false

networkTimeout​

Maximum timeout duration for NetFUNNEL server API requests before considering them transient failures.

PropertyValue
Unitmilliseconds (ms)
Range100–10000
Default3000
Applies toNetFUNNEL server endpoints only

Behavior:

  • No response within timeout → Transient Failure
  • Immediate error response → No timeout wait
  • Each retry uses the same timeout setting

Examples:

  • networkTimeout = 1000 → 1 second timeout
  • networkTimeout = 5000 → 5 second timeout

Important Notes:

  • Too short values may cause normal requests to be treated as timeouts
  • With networkTimeout = 3000 and retryCount = 3, maximum wait time is 12 seconds before onNetworkError callback
  • Even if error response arrives in 35ms, retry will wait 2.965 seconds before next attempt

retryCount​

Number of additional retry attempts for transient failures in NetFUNNEL server API calls.

PropertyValue
Range0–10
Default0
FormulaTotal attempts = (setting value) + 1
Applies toNetFUNNEL server endpoints only

Behavior:

  • Transient Failure → triggers retry (if retry count > 0)
  • Permanent Failure → all retry attempts exhausted
  • Each retry respects the networkTimeout setting

Examples:

  • retryCount = 0 → No retry (single attempt)
  • retryCount = 1 → 1 initial + 1 retry (2 total attempts)
  • retryCount = 2 → 1 initial + 2 retries (3 total attempts)

Important Notes:

  • If request succeeds during retry, retry process stops immediately
  • After all retry attempts are exhausted, onNetworkError callback is triggered
  • Each retry respects the networkTimeout setting

useNetworkRecoveryMode​

Prevents users from being kicked out of waiting rooms due to network issues. When enabled, users stay in their waiting state (modal or waiting room) even when network problems occur, and automatically resume when connectivity is restored.

PropertyValue
Defaultfalse
Applies to5002 (entry check) requests only
Core BenefitNo interruption to waiting experience during network issues

The Problem This Solves:

  • Without recovery mode: Network failure → Error page/callback → User loses waiting position
  • With recovery mode: Network failure → Stay in waiting → Auto-resume when network recovers

Behavior:

Mode5002 (Entry Check)User Experience
trueStay in waiting, auto-recoverNo interruption
falseNormal retry → Error handlingError page/callback

Recovery Scenarios:

  • Quick recovery: Keep existing key/sequence (maintains queue position)
  • Extended outage: Get new key/sequence (position may reset)

Important Notes:

  • useNetworkRecoveryMode = true only maintains waiting room during network failures while waiting
  • If network fails before waiting starts, onNetworkError callback is still triggered
  • This setting prevents users from losing their waiting position due to temporary network issues

Debugging Options​

Enable debugging and logging features.

ParameterTypeRequiredDefaultOptions
printLogBooleanOptionalfalsetrue/false

printLog​

Print NetFUNNEL logs to Logcat.

Usage:

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

Check logs in Logcat:

  1. Open Android Studio Logcat
  2. Filter by package:mine NetFUNNEL
  3. Look for NetFUNNEL log messages

Log Output:

  • Initialization status
  • Network request details
  • Callback responses
  • Error messages
  • Key management events

Template Options​

Control waiting room appearance and templates.

ParameterTypeRequiredDefaultOptions
useNetfunnelTemplateBooleanOptionaltruetrue/false

useNetfunnelTemplate​

Use the default NetFUNNEL waiting room template.

Options:

  • true (default): Uses NetFUNNEL's standard waiting room template
  • false: Allows custom waiting room template implementation

Custom Template Implementation:

When useNetfunnelTemplate = false, you must implement custom waiting room UI and handle the onContinue callback to receive real-time waiting information.

onContinue Callback Parameters:

ParameterTypeDescriptionExample
statusCodeIntResponse code for waiting status201
messageStringMessage for waiting status"Continue"
aheadWaitIntNumber of users ahead in queue{{N}}
behindWaitIntNumber of users behind in queue{{N}}
waitTimeStringExpected waiting time{{HH:mm:ss}}
progressRateIntProgress percentage{{0~100}}

Basic Custom Template Example:

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)
    }
}

Complete Custom Dialog Implementation:

1. Initialize with Custom Template:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    useNetfunnelTemplate = false  // Enable custom template
)

2. Custom Dialog XML Layout:

<!-- dialog_netfunnel.xml -->
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:background="@drawable/bg_dialog_rounded"
    android:orientation="vertical"
    android:padding="24dp">
    
    <TextView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Expected Wait Time"
        android:textSize="16sp"
        android:textStyle="bold" />
        
    <TextView
        android:id="@+id/txt_wait_time"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="00:00:00"
        android:textSize="28sp"
        android:textStyle="bold" />
        
    <ProgressBar
        android:id="@+id/progress_bar"
        style="?android:attr/progressBarStyleHorizontal"
        android:layout_width="match_parent"
        android:layout_height="12dp"
        android:progress="50" />
        
    <TextView
        android:id="@+id/txt_front_queue"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Users ahead: 0"
        android:textSize="15sp" />
        
    <TextView
        android:id="@+id/txt_behind_queue"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Users behind: 0"
        android:textSize="15sp" />
        
    <Button
        android:id="@+id/btn_cancel"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Close"
        android:textSize="15sp" />
</LinearLayout>

3. Custom Dialog Controller:

class NetfunnelDialog(
    context: Context,
    private val onClose: () -> Unit
) : Dialog(context) {
    private lateinit var binding: DialogNetfunnelBinding
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = DialogNetfunnelBinding.inflate(layoutInflater)
        setContentView(binding.root)
        
        binding.btnCancel.setOnClickListener {
            closeDialog()
        }
    }
    
    private fun closeDialog() {
        dismiss()
        onClose()  // Call Netfunnel.nfStop() to properly terminate waiting
    }
    
    fun updateDialog(aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        "Users ahead: $aheadWait".also { binding.txtFrontQueue.text = it }
        "Users behind: $behindWait".also { binding.txtBehindQueue.text = it }
        binding.txtWaitTime.text = waitTime
        binding.progressBar.progress = progressRate
    }
}

4. Complete Callback Implementation:

private val callback = object : NetfunnelCallback() {
    override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        activity.runOnUiThread {
            if (dialog == null) {
                dialog = NetfunnelDialog(activity) { 
                    Netfunnel.nfStop("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", stopCallback)
                }.apply {
                    setCanceledOnTouchOutside(false)
                    show()
                }
            }
            dialog?.updateDialog(aheadWait, behindWait, waitTime, progressRate)
        }
    }
    
    override fun onSuccess(statusCode: Int, message: String) {
        dialog?.dismiss()
        dialog = null
        // Navigate to main activity
    }
    
    override fun onError(statusCode: Int, message: String) {
        dialog?.dismiss()
        dialog = null
        // Handle error
    }
}

Important Notes:

  • Dialog creation: Create dialog only once, then update UI with updateDialog()
  • UI updates: Always use runOnUiThread for UI modifications
  • Proper termination: Call Netfunnel.nfStop() when closing dialog to return entry key
  • Limited functionality: Custom templates have restrictions on advanced waiting room features
  • Recommendation: Use useNetfunnelTemplate = true for full functionality unless custom UI is required

Error Handling Options​

Control how errors are handled and displayed to users.

ParameterTypeRequiredDefaultOptions
errorBypassBooleanOptionalfalsetrue/false

errorBypass​

Treat Error/NetworkError as Success.

Behavior:

  • false (default): Normal error handling (callbacks/redirects on errors)
  • true: Treats errors as success, allowing service to continue (bypass mode)

When errorBypass = true:

  • onError and onNetworkError callbacks are not called
  • Instead, onSuccess callback is triggered
  • Only onSuccess callback needs to be implemented
  • All error situations are bypassed

Use Cases for errorBypass = true:

  • Testing environments
  • Services where network connectivity doesn't affect core functionality
  • Simple event participation systems
  • Development and debugging scenarios

Important Warning:

  • errorBypass = true bypasses all error situations
  • Use with caution as it may hide important network issues
  • Not recommended for production environments with critical traffic control needs

Error Types Handled:

  • Network errors (1001, 1002)
  • Server errors (500)
  • User cancellation (499)
  • Invalid configuration errors

Code-based Integration Callbacks: When errorBypass = false, the following callbacks are triggered:

  • onNetworkError: For network-related errors (1001, 1002)
  • onError: For server errors (500)
  • onClose: For user cancellation (499)

Network Error Callbacks​

NetFUNNEL Android Agent provides detailed network error information through onNetworkError callback.

Network Error Types:

Status CodeMessageDescription
1001Network Not ConnectedNetwork connection blocked (WiFi/cellular data disabled)
1002Network TimeoutNetwork response delay causing timeout

Network Error Handling Example:

private val callback = object : NetfunnelCallback() {
    override fun onNetworkError(statusCode: Int, message: String) {
        when (statusCode) {
            1001 -> {
                // Network connection blocked - show immediate user guidance
                showToast("네트워크 연결에 실패했습니다. 네트워크 설정을 확인해 주세요.", activity)
            }
            1002 -> {
                // Network timeout - navigate to retry screen
                navigateToNetworkErrorActivity(activity)
            }
        }
    }
}

Error Handling Strategy:

  • 1001 (Network Not Connected): Immediate user guidance (toast message, dialog)
  • 1002 (Network Timeout): Navigate to error screen with retry option

UI Configuration​

Control waiting room UI appearance and behavior.

ParameterTypeRequiredDefaultOptions
statusBarStyleString?Optionalnullnull, "auto", "black", "white"

statusBarStyle​

Control status bar style and icon colors for NetFUNNEL waiting room (WebView).

Available Values:

ValueDescriptionBehavior
null (default)Use app's default themeStatus bar remains visible, no FullScreen mode
"auto"Automatic icon color based on themeLight mode: black icons, Dark mode: white icons
"black"Always black iconsFixed black icon color regardless of theme
"white"Always white iconsFixed white icon color regardless of theme

Behavior Details:

Default Value (null):

  • Follows app's default theme settings
  • FullScreen mode is not applied
  • Status bar remains visible as normal

Option Values ("auto", "black", "white"):

  • FullScreen mode is automatically applied
  • Status bar becomes transparent
  • Icon colors are controlled based on the selected option

Usage Examples:

1. Default Behavior:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = null  // Use app's default theme
)

2. Automatic Icon Color:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = "auto"  // Auto-adjust icon color based on theme
)

3. Fixed Black Icons:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = "black"  // Always black icons
)

4. Fixed White Icons:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = "white"  // Always white icons
)

Important Notes:

  • FullScreen Mode: When using any option value ("auto", "black", "white"), FullScreen mode is automatically applied
  • Transparency: Status bar becomes transparent when option values are used
  • Theme Compatibility: "auto" option automatically adapts to light/dark themes
  • Icon Visibility: Choose appropriate icon color based on your waiting room background
Status Bar Configuration Guide

For detailed information about status bar configuration options, see the Feature Guide - Waiting Room Status Bar Settings.

Advanced Options​

Additional configuration options for advanced use cases.

ParameterTypeRequiredDefaultOptions
userIdString?OptionalnullUser identifier string

userId​

Set user identifier for whitelist/blacklist management.

Usage:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    userId = "user_67890" // User-specific identifier
)

Use Cases:

  • Whitelist specific users
  • Blacklist problematic users
  • User-specific traffic control
  • Analytics and monitoring

Complete Example​

Here's a complete initialization example with all options:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    networkTimeout = 5000,
    retryCount = 2,
    printLog = false,
    errorBypass = false,
    useNetfunnelTemplate = true,
    userId = "user_67890",
    useNetworkRecoveryMode = true,
    statusBarStyle = null
)