Android Agent v4.1.1

⭐️ Agent Requirements: Java 1.8 / Android SDK 21(Lollipop) or higher

NetFUNNEL Agent is a dedicated NetFUNNEL client used to communicate with the NetFUNNEL server. Users can apply and implement various functions provided by the agent into the client application code to apply a virtual waiting room.

Android Agent Flowchart

NetFUNNEL Agent operates generally as shown above.

1. Before Waiting

• Before waiting, initialize the configuration information. This process involves fetching configuration information from the NetFUNNEL server and initializing objects based on that information.
• Use the provided initialization function to initialize the configuration information of the NetFUNNEL agent.

2. During Waiting

• This process involves waiting at a specific part of the page (view or activity) where you want to apply traffic waiting by exposing the virtual waiting room.
• Apply the virtual waiting room using the provided start waiting function.

3. After Waiting

• This is the process after waiting ends. There are three reasons why a user might end waiting: success in entry, failure in entry, or cancellation of waiting.
• Implement the logic after waiting ends using the provided callback function and completion processing function.

How to Apply the Agent

Step 1. Add the Library

Download the library and add it to Gradle as shown below.

build.gradle

implementation files('libs/netfunnel-android-agent_latest.aar')

build.gradle.kts

implementation(files("libs/netfunnel-android-agent_latest.aar"))

Step 2. Initialize Configuration Information

The first step in applying the agent is to initialize the configuration information of the NetFUNNEL agent using the provided initialization function.

Before using NetFUNNEL features, initialize using the InitNetfunnel and InitEum functions.

public class Activity extends AppCompatActivity {
    // ...
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity);
        
        // NetFUNNEL initialization
        Init();
        
        // ...
    }
    // ...
    
    // NetFUNNEL configuration information initialization
    public void Init() {
        Netfunnel.getInstance().InitNetfunnel(
            "{Application Name}", // Application name
            "{tenant API URL}",   // API Server URL
            "{tenant NF URL}",    // NetFUNNEL Server URL
            "{nf-setting URL}",   // NetFUNNEL Setting File URL
            "{network Timeout}",  // Maximum timeout for NetFUNNEL request
            this                  // Activity for creating waiting/blocking window
        );
        
        Netfunnel.getInstance().InitEum(
            "{EUM Server URL}", // EUM Server URL
            "{timeout}",        // Maximum timeout for EUM request
            this
        );
        
        Netfunnel.getInstance().EUMCollectYN(true); // Enable EUM collection
    }
}

Step 3. Implement Callback Functions After Waiting Ends

When waiting ends in the virtual waiting room, various situations trigger callback functions. You can handle success or blocking processing based on the type of callback function and implement various user scenarios that occur when waiting is canceled by implementing callback functions.

The callback functions are defined in the AgentInterface class, which is an interface for defining actions based on NetFUNNEL control responses. You can inherit the AgentInterface class in a separate class and implement the internal callback functions, or you can implement the internal callback functions from the constructor of the AgentInterface class as shown below.

Implementing Callback Functions Through the Constructor of the AgentInterface Class

AgentInterface agentInterface = new AgentInterface() {
    @Override
	public void onSuccess() {
	 /*
	  * Called when entry is successful after waiting ends (or when the request fails due to a NetFUNNEL server issue)
	  */
	}
 
	@Override
	public void onCancel() {
	 /*
	  * Called when the cancel button is clicked on the waiting screen
	  */
	}
 
	@Override
	public void nfLog(String _message) {
	  /*
	   * Logs recorded in the NetFUNNEL library (used for debugging the NetFUNNEL library)
	   * Example: nfLog.d(_message)
	   */
	}
 
	@Override
	public void onNetworkDisconnect() {
	   /*
		* Called when a NetFUNNEL server request fails due to network disconnection of the device
		*/
	}
 
	@Override
	public void onKeyError() {
		/*
		 * Called when there is a key issue
		 * Example: requesting with an expired key, non-existent key, or incorrect key
		 */
	}
 
	@Override
	public void onBlock() {
		/*
		 * Called when project access mode setting is disabled in the SCP administrator console
		 */
	}
 
	@Override
	public void onIpBlock() {
		/*
		 * Called when blocked due to macro blocking setting in the SCP administrator console
		 */
	}
};

Refer to the detailed flowchart of the agent for implementing all callback functions related to entry success.

Implementing Callbacks When Entry is Successful

When entry is successful, implement two things: 1️⃣ Code for entering the target page
2️⃣ Call the completion processing function to return the issued key to the NetFUNNEL server

Completion Processing Function

Function name: NFStop

The following is an example of implementing the onSuccess() callback function:

AgentInterface agentInterface = new AgentInterface() {
  @Override
  public void onSuccess() {
      // Execute the basic control stop function
      Netfunnel.getInstance().NFStop("{projectKey}", "{segmentKey}");
  
      // Perform activity transition
      runOnUiThread(new Runnable() {
          @Override
          public void run() {
              Intent intent = new Intent(CurrentActivity.this, NewActivity.class);
              startActivity(intent);
          }
      });
  }
};

Implementing Callbacks When Entry is Blocked

Entry is usually blocked due to frequent macro-like requests or malicious requests with incorrect keys. In such scenarios, you can typically implement logic to enhance user experience as follows:

1️⃣ If you want to stay on the current page, no need to implement any logic
2️⃣ Implement logic to display a modal window indicating that entry is blocked
3️⃣ Implement logic to navigate to a specific page indicating that entry is blocked
4️⃣ Implement logging logic

In cases of entry being blocked or failed, you can implement such logic without needing to call the completion processing function.

The following is an example of implementing the onBlock callback function:

AgentInterface agentInterface = new AgentInterface() {
    @Override
    public void onBlock() {
        /*
		1. If you want to stay on the current page, no need to implement any logic
		2. Implement logic to display a modal window indicating that entry is blocked
		3. Implement logic to navigate to a specific page indicating that entry is blocked
		4. Implement logging logic
		*/
    }
};

Implementing Callbacks When Waiting is Canceled

When the end-user presses the cancel waiting button while waiting in the virtual waiting room, the cancel waiting callback can be called. In such scenarios, you can typically implement logic to enhance user experience as follows:

1️⃣ If you want to stay on the current page, no need to implement any logic
2️⃣ Implement logic to display a modal window indicating that waiting is canceled
3️⃣ Implement logic to navigate to a specific page indicating that waiting is canceled
4️⃣ Implement logging logic

In cases of waiting being canceled, you can implement such logic without needing to call the completion processing function. The following is an example of implementing the onCancel callback function when the cancel waiting button is pressed:

AgentInterface agentInterface = new AgentInterface() {
    @Override
    public void onCancel() {
        /*
		1. If you want to stay on the current page, no need to implement any logic
		2. Implement logic to display a modal window indicating that waiting is canceled
		3. Implement logic to navigate to a specific page indicating that waiting is canceled
		4. Implement logging logic
		*/
    }
};

💡 Tip. How to Display a Separate Modal Window and Restart Waiting When the Cancel Waiting Button is Pressed

AgentInterface agentInterface = new AgentInterface() {
    @Override
    public void onCancel() {
        AlertDialog.Builder builder = new AlertDialog.Builder(activity);
        builder.setTitle("Notification");
        builder.setMessage("Do you want to exit the app or retry entry?");
        builder.setPositiveButton("Exit", new DialogInterface.OnClickListener() {
            @Override
            public void onClick(DialogInterface dialog, int which) {
                activity.finish();
            }
        });
 
        builder.setNegativeButton("Retry Entry", new DialogInterface.OnClickListener() {
            @Override
            public void onClick(DialogInterface dialog, int which) {
                Netfunnel.getInstance().NFStart(projectKey, segmentKey, agentInterface);
            }
        });
        builder.show();
    }
};

Step 4. Start Waiting

To apply traffic waiting by exposing the virtual waiting room at a specific part of the page (view or activity) where you want to apply traffic waiting, use the provided start waiting function.

Call the NFStart() function in the code section that exposes the NetFUNNEL virtual waiting room to end-users.

Netfunnel.getInstance().NFStart("{project Key}", "{segment Key}", agentInterface);

Appendix

Object, Class

Netfunnel Function

InitNetfunnel
Receives initialization data for NetFUNNEL functionality and reads NetFUNNEL settings values. Detailed parameters can be copied from the values in the Agent tab on the Console page.

NFStart
Starts the basic control of NetFUNNEL.

NFStop
Returns the NetFUNNEL key.

NFStartSection
Starts section control of NetFUNNEL.

NFStopSection
Ends section control and returns the key.

InitEum
Initializes the Eum function to use the End User Monitoring feature.

EUMBegin
You can directly set the section start of the End User Monitoring feature using this function.

EUMEnd
Measures the time taken from EUMBegin to EUMEnd and sends it along with separate collected data.

EUMCollectYN
You can disable EUM collection using this function.

AgentInterface Function

onSuccess
Called when a NetFUNNEL response is successful.

onCancel
Called when the user requests to cancel waiting/blocking.

onNetworkDisconnect
Called when a request to the NetFUNNEL server fails due to the network being blocked on the device.

onKeyError
Called when requesting with an expired, non-existent, or incorrect key.

onBlock
Called when project access mode setting is disabled in the administrator console.

onIpBlock
Called when blocked due to frequent requests from macro blocking in the administrator console.

nfLog
Logs are delivered through this function so that the user can understand the internal operation of the library while testing the app.