Skip to main content
Version: 4.6.1

API Reference

Complete reference for NetFUNNEL Android Agent functions, callbacks, and response formats.

Table of Contents​

Initialization Functions​

Netfunnel.initialize​

Purpose: Initialize the NetFUNNEL Android Agent with required configuration.

Function Signature:

Netfunnel.initialize(
    clientId: String,
    networkTimeout: Long = 3000,
    retryCount: Int = 0,
    printLog: Boolean = false,
    errorBypass: Boolean = false,
    useNetfunnelTemplate: Boolean = true,
    userId: String? = null,
    useNetworkRecoveryMode: Boolean = false,
    statusBarStyle: String? = null
)

Quick Parameter Overview:

CategoryParametersPurpose
RequiredclientIdEssential client configuration
NetworknetworkTimeout, retryCount, useNetworkRecoveryModeNetwork behavior and reliability
DebuggingprintLogEnable debug logging
Error HandlingerrorBypassControl error behavior
UI/TemplateuseNetfunnelTemplate, statusBarStyleWaiting room appearance
AdvanceduserIdUser identification for whitelist/blacklist

Basic Example:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}"
)

Complete Example with All Options:

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    networkTimeout = 5000,
    retryCount = 2,
    printLog = true,
    errorBypass = false,
    useNetfunnelTemplate = true,
    userId = "user_12345",
    useNetworkRecoveryMode = true,
    statusBarStyle = "auto"
)
Complete Configuration Reference

For detailed information about all initialization parameters, their ranges, behavior, and usage examples, see the Configuration Options Reference.

Basic Control Functions​

Basic Control limits the entry speed to your service. When the start function is called, a key is issued and the waiting room appears. When the stop function is called, the key is returned.

nfStart​

Purpose: Issue a key and display the waiting room for basic control.

Function Signature:

Netfunnel.nfStart(
    projectKey: String,
    segmentKey: String,
    callback: NetfunnelCallback,
    activity: Activity
)

Parameters:

ParameterTypeDescriptionRequired
projectKeyStringBasic Control project key from consoleYes
segmentKeyStringBasic Control segment key from consoleYes
callbackNetfunnelCallbackCallback to handle VWR eventsYes
activityActivityCurrent activity contextYes

Returns: void

Example:

Netfunnel.nfStart(
    projectKey = "service_1",
    segmentKey = "segKey_8612",
    callback = myCallback,
    activity = this
)

nfStop​

Purpose: Return the key after entry is completed.

Function Signature:

Netfunnel.nfStop(
    projectKey: String,
    segmentKey: String,
    completeCallback: NetfunnelCompleteCallback? = null
)

Parameters:

ParameterTypeDescriptionRequired
projectKeyStringBasic Control project key from consoleYes
segmentKeyStringBasic Control segment key from consoleYes
completeCallbackNetfunnelCompleteCallback?Callback for key return confirmationNo

Returns: void

Example:

Netfunnel.nfStop(
    projectKey = "service_1",
    segmentKey = "segKey_8612",
    completeCallback = myCompleteCallback
)
Auto-return Timeout

If you do not execute the stop function, the key will be returned automatically according to the segment timeout setting (default timeout: 20 seconds).

Section Control Functions​

Section Control maintains a fixed number of concurrent users in a specific section. When the start function is called, a key is issued; until the stop function is called, the user is considered to be in the active section, and the next user in the queue is not admitted.

Use Cases:

  • Multi-step processes: After entering an event page, purchasing products, and clicking the payment completion button
  • User session management: From user login until logout
  • Resource-intensive operations: Maintaining optimal user count for specific features

nfStartSection​

Purpose: Issue a key and display the waiting room for section control.

Function Signature:

Netfunnel.nfStartSection(
    projectKey: String,
    segmentKey: String,
    callback: NetfunnelCallback,
    activity: Activity
)

Parameters:

ParameterTypeDescriptionRequired
projectKeyStringSection Control project key from consoleYes
segmentKeyStringSection Control segment key from consoleYes
callbackNetfunnelCallbackCallback to handle VWR eventsYes
activityActivityCurrent activity contextYes

Returns: void

Example:

Netfunnel.nfStartSection(
    projectKey = "service_1",
    segmentKey = "section_segKey_1234",
    callback = myCallback,
    activity = this
)

nfStopSection​

Purpose: Return the key when the user exits the active section.

Function Signature:

Netfunnel.nfStopSection(
    projectKey: String,
    segmentKey: String,
    completeCallback: NetfunnelCompleteCallback? = null
)

Parameters:

ParameterTypeDescriptionRequired
projectKeyStringSection Control project key from consoleYes
segmentKeyStringSection Control segment key from consoleYes
completeCallbackNetfunnelCompleteCallback?Callback for key return confirmationNo

Returns: void

Example:

Netfunnel.nfStopSection(
    projectKey = "service_1",
    segmentKey = "section_segKey_1234",
    completeCallback = myCompleteCallback
)
Section Control Behavior

If you do not execute the stop function, the user is considered to remain in the active section, which may delay the next user's admission.

Callback Classes​

NetfunnelCallback​

Purpose: Handle responses from NetFUNNEL server for start functions.

Android Interface Requirements

In Android, NetfunnelCallback is an interface that requires implementing ALL methods. You cannot implement only some methods - you must provide implementations for all callback methods. However, some methods are more critical than others. For basic implementations, you can use TODO("Not yet implemented") for optional methods, but you should replace these with proper implementations in production code.

Abstract Methods:

MethodRequiredDescriptionImplementation Strategy
onSuccessYesCalled when entry is granted or bypassedAlways implement - Core business logic
onErrorYesCalled when a system error occursAlways implement - Usually proceed with business logic
onNetworkErrorYesCalled when network connection issues occurAlways implement - Retry or proceed with business logic
onBlockOptionalCalled when user is blockedCan use TODO initially - Show blocked message
onCloseOptionalCalled when user closes waiting roomCan use TODO initially - Handle user cancellation
onContinueOptionalCalled for custom waiting room updatesCan use TODO initially - Only needed for custom waiting rooms

Basic Implementation (Step-by-Step):

For initial development, you can implement only the essential methods and use TODO for others:

import com.nf4.NetfunnelCallback

class StartCallback {
    companion object {
        private const val TAG = "NetFUNNEL"
    }
    
    private val callback = object : NetfunnelCallback() {
        override fun onSuccess(statusCode: Int, message: String) {
            Log.d(TAG, "onSuccess $statusCode $message")
            // Core business logic - ALWAYS implement
            proceedWithAction()
        }
        
        override fun onError(statusCode: Int, message: String) {
            Log.d(TAG, "onError $statusCode $message")
            // Usually proceed with business logic - ALWAYS implement
            proceedWithAction()
        }
        
        override fun onNetworkError(statusCode: Int, message: String) {
            Log.d(TAG, "onNetworkError $statusCode $message")
            // Retry or proceed with business logic - ALWAYS implement
            proceedWithAction()
        }
        
        override fun onBlock(statusCode: Int, message: String) {
            TODO("Not yet implemented")
        }
        
        override fun onClose(statusCode: Int, message: String) {
            TODO("Not yet implemented")
        }
        
        override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
            TODO("Not yet implemented")
        }
    }
    
    fun getCallback(): NetfunnelCallback = callback
}

Complete Implementation (Production Ready):

For production code, implement all methods with proper handling:

import com.nf4.NetfunnelCallback

class StartCallback {
    companion object {
        private const val TAG = "NetFUNNEL"
    }
    
    private val callback = object : NetfunnelCallback() {
        override fun onSuccess(statusCode: Int, message: String) {
            Log.d(TAG, "onSuccess $statusCode $message")
            /**
             * Queue passage processing logic
             * ex - Service screen entry processing
             */
            proceedWithAction()
        }
        
        override fun onError(statusCode: Int, message: String) {
            Log.d(TAG, "onError $statusCode $message")
            /**
             * System error handling logic - proceed with business logic to maintain service availability
             * ex - Server errors are typically temporary and shouldn't block user access
             */
            proceedWithAction()
        }
        
        override fun onNetworkError(statusCode: Int, message: String) {
            Log.d(TAG, "onNetworkError $statusCode $message")
            /**
             * Network error handling logic - log only, don't execute business logic
             * ex - Use useNetworkRecoveryMode = true for automatic network recovery
             */
            // Note: Business logic not executed here - relies on network recovery mode
        }
        
        override fun onBlock(statusCode: Int, message: String) {
            Log.d(TAG, "onBlock $statusCode $message")
            /**
             * User entry blocking processing logic
             * ex - Show access restriction message
             */
            showBlockedMessage()
        }
        
        override fun onClose(statusCode: Int, message: String) {
            Log.d(TAG, "onClose $statusCode $message")
            /**
             * User cancellation processing logic (WebView closes and returns to previous screen automatically)
             * ex - Show exit notification Toast
             */
            handleUserCancel()
        }
        
        override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
            Log.d(TAG, "onContinue $statusCode $message")
            /**
             * Waiting progress UI update logic (only applicable when using custom waiting room)
             * ex - Update real-time waiting information to custom waiting screen
             */
            updateCustomWaitingRoom(aheadWait, behindWait, waitTime, progressRate)
        }
    }
    
    fun getCallback(): NetfunnelCallback = callback
}

Response Handling Strategy:

Response TypeStatus CodeActionBusiness LogicUser Notification
Success200, 300, 303Execute✅ YesOptional
Error500Execute✅ YesOptional
NetworkError1001, 1002Log Only❌ NoOptional
Block301, 302Stop❌ NoRequired
Close495-499Stop❌ NoOptional

Why onError Executes Business Logic but onNetworkError Doesn't:

onError (Status Code 500) - Server Error:

  • Scenario: NetFUNNEL server encounters internal errors
  • Strategy: Execute business logic to maintain service availability
  • Rationale: Server errors are typically temporary and shouldn't block user access
  • Result: Robust service that continues even when NetFUNNEL has issues

onNetworkError (Status Code 1001, 1002) - Network Issues:

  • Scenario: Network connectivity problems (offline, timeout)
  • Strategy: Log only, don't execute business logic
  • Rationale: Use useNetworkRecoveryMode = true for automatic network recovery
  • Result: Users stay in waiting room during network issues and auto-resume when connectivity returns

Network Recovery Mode Configuration:

Enable network recovery in your Application class for optimal network error handling:

// SampleApplication.kt
Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    useNetworkRecoveryMode = true  // Enable automatic network recovery
)

NetfunnelCompleteCallback​

Purpose: Handle responses from NetFUNNEL server for stop functions.

Abstract Methods:

MethodRequiredDescription
onCompleteNoCalled when key return is completed

Example Implementation:

import com.nf4.NetfunnelCompleteCallback

class StopCallback {
    companion object {
        private const val TAG = "NetFUNNEL"
    }
    
    private val callback = object : NetfunnelCompleteCallback() {
        override fun onComplete(statusCode: Int, message: String) {
            Log.d(TAG, "onComplete $statusCode $message")
            /**
             * Entry key return result processing logic
             * ex - Navigate to next page when key return is successful
             */
            handleKeyReturnCompletion()
        }
    }
    
    fun getCallback(): NetfunnelCompleteCallback = callback
}

Response Object Schema​

The callback methods receive the following parameters:

ParameterTypeDescriptionExample
statusCodeIntHTTP status code200, 300, 500, 1001, etc.
messageStringResponse message"Success", "Bypass", "Server Error", etc.
aheadWaitIntUsers ahead in queue (onContinue only)5
behindWaitIntUsers behind in queue (onContinue only)10
waitTimeStringEstimated wait time (onContinue only)"2 minutes"
progressRateIntProgress percentage (onContinue only)75

Status Codes Reference​

Complete reference for all possible status codes and their meanings.

StatusStatusCodeMessageDescription
Success200SuccessSuccessfully passed the queue and entered the service. Normal queue passage.
300BypassEntry bypassed due to various conditions. Examples: subscription/license expired, project/segment deactivated in console, errorBypass=true setting and error occurred.
303ExpressExpress entry succeeded. IP or ID registered in console whitelist (admin bypass).
Error500Server ErrorSystem error occurred. Examples: agent initialization function not called before start function, non-existent project/segment key used, segment deleted in console, server error causing partial response loss.
NetworkError1001Network Not ConnectedNetwork connection blocked. WiFi/cellular data disabled.
1002Network TimeoutNetwork timeout occurred. Examples: network latency, invalid waiting room HTML URL received, server down (502, etc.).
Block301BlockSegment is in block state. Segment blocked in console (benevolent entry blocking).
302Macro BlockUser blocked. Examples: IP or ID registered in console blacklist (admin blocking), BotManager Basic enabled (malicious entry blocking).
Close495Closed PostWaiting RoomClosed the post-waiting room. User clicked close button in post-waiting room.
496Closed PreWaiting RoomClosed the pre-waiting room. User clicked close button in pre-waiting room.
497Closed Macro Blocking RoomClosed the macro blocking room. User clicked close button in macro blocking room.
498Closed Blocking RoomClosed the blocking room. User clicked close button in blocking room.
499Canceled Waiting RoomClicked the cancel/close button in the standard waiting room. User clicked cancel button in standard waiting room.
Continue201ContinueWaiting room update for custom template. Agent useNetfunnelTemplate=false setting and during basic waiting.

Utility Functions​

getVersion​

Purpose: Get the current version of the NetFUNNEL Android Agent.

Function Signature:

Netfunnel.getVersion(): String

Returns: String - The version string of the NetFUNNEL Android Agent

Example:

val version = Netfunnel.getVersion()
Log.d("NetFUNNEL", "Agent version: $version")