React Native Agent

Overview

The NetFUNNEL React Native agent is a dedicated client that communicates with the NetFUNNEL server.

Minimum Requirements

• react-native 0.70.0 or later
• react-native-webview 13.0.0 or later
• react-native-async-storage/async-storage 1.23.1 or later

Agent Operation Flow

Queue control points can be configured via segment trigger rules in the NetFUNNEL console. The queue is applied when the URL of the page the user accesses matches the trigger rules.

Before waiting: Page load → Agent initialization → Trigger rule match While waiting: NetFUNNEL server request → NetFUNNEL key issuance → Move to waiting room page After waiting: Service page entry → NetFUNNEL key return

Agent Installation

Add Library

Add Dependencies

Copy the code below and add the dependency to your package.json.

package.json

{
  "dependencies": {
    "netfunnel-rn-agent": "https://agent-lib.stclab.com/agents/static/rn/netfunnel-rn-agent-latest.tgz"
  }
}

Install Packages

From the project root, run the following command to install packages.

npm install

Agent Application

Initialization

The Netfunnel.initialize function initializes the Netfunnel service and configures communication between the client and the server.

This function must be called at application startup and accepts a configuration object that includes required parameters such as clientId to define Netfunnel behavior.

Once initialization is complete, Netfunnel runs according to the specified settings and you can use Netfunnel features.

info

You can find {{CLIENT_ID}} by clicking the profile icon in the top right of the console and opening the "Integration credentials" menu.

import Netfunnel from 'netfunnel-rn-agent';
Netfunnel.initialize({
    clientId: '{{CLIENT_ID}}'
});

Parameter	Description	Required	Condition/Default
clientId	User unique identifier	O	Cannot be empty string
serverUrl	NetFUNNEL server address	X	None (default address used)
errorUrl	NetFUNNEL error page HTML address	X	None (default address used)
networkTimeout	Maximum time to wait for network response	X	Default: 3,000ms / Max: 10,000ms / Min: 100ms
retryCount	Number of retries on network request failure	X	Default: 0 / Max: 10 / Min: 0
printLog	Whether to output logs for debugging	X	Default: false
errorBypass	Whether to bypass on error	X	Default: false
useNetfunnelTemplate	Whether to use the custom NetFUNNEL waiting room from the console	X	Default: true
userId	End-user unique identifier for blacklist/whitelist	X	Default: null
useNetworkRecoveryMode	When the connection is lost while the waiting room is open, keep the waiting room and retry within networkTimeout	X	Default: false

Netfunnel WebView Component

<Netfunnel.WebViewComponent /> is a component that renders Netfunnel's waiting room in a WebView in your React Native application.

This component runs using the parameters set by Netfunnel.initialize, displays the waiting room UI to the user, and handles interaction with the NetFUNNEL server.

Place it alongside the App component's NavigationContainer so the waiting room WebView is rendered independently of the app's navigation flow.

export default function App() {
	return (
		<View>
			<NavigationContainer>
            ...
			</NavigationContainer>
			<Netfunnel.WebViewComponent />
		</View>
	);
}

Basic Control

Basic Control: Start function

• Name: nfStart
• Description: Call at the point where you want to apply waiting to issue a key and show the waiting room.
• Where to use: On page entry or at the start of an event.

Parameter	Type	Description	Required
projectKey	String	NetFUNNEL console Basic Control project key	O
segmentKey	String	NetFUNNEL console Basic Control segment key	O
callback	Function	User-defined callback for waiting room events	O

Netfunnel.nfStart("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", function(response) {
  // TODO: Implement callback logic based on response.
  nfCallback(response);
});

Basic Control: Stop function

• Name: nfStop
• Description: Call after entry is complete to return the key.
• Where to use: After the start function completes or when the entered user's activity is finished.

warning

If you do not call the stop function, the key is returned automatically according to the segment timeout setting.

Parameter	Type	Description	Required
projectKey	String	NetFUNNEL console Basic Control project key	O
segmentKey	String	NetFUNNEL console Basic Control segment key	O

Netfunnel.nfStop("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}");

Section Control

Section control keeps the number of concurrent users in a specific section of the application constant. A key is issued when the start function is called, and until the stop function is called the user is considered to be in the activity section so the next user in line is not let in. Calling the stop function returns the key and allows the next user to enter.

Section Control: Start function

• Name: nfStartSection
• Description: Call at the point where you want to apply waiting to issue a key and show the waiting room.
• Where to use: On page entry or at the start of an event.

Parameter	Type	Description	Required
projectKey	String	NetFUNNEL console Section Control project key	O
segmentKey	String	NetFUNNEL console Section Control segment key	O
callback	Function	User-defined callback for waiting room events	O

Netfunnel.nfStartSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", function(response) {
  // TODO: Implement callback logic based on response.
  nfCallback(response);
});

Section Control: Stop function

• Name: nfStopSection
• Description: Call after entry is complete to return the key.
• Where to use: When the entered user's activity section ends.

warning

If you do not call the stop function, the user is considered to remain in the activity section and the next user's entry may be delayed.

Parameter	Type	Description	Required
projectKey	String	NetFUNNEL console Section Control project key	O
segmentKey	String	NetFUNNEL console Section Control segment key	O

Netfunnel.nfStopSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}");

Callback Function

The callback passed as the third parameter of the Basic Control and Section Control start functions receives the response from the NetFUNNEL server. You can implement different logic depending on the response.

info

You must handle the status values 'Success', 'Error', and 'NetworkError'. Other status values do not need to be handled for the service to work.

Success

statusCode	message	Description
200	Success	Passed the queue and entered the service
300	Bypass	Subscription/license expired<br/>Project/segment deactivated<br/>data-nf-error-bypass=true set
303	Express	Behavior on entry success

Error

statusCode	message	Description
500	Server Error	Invalid project/segment key<br/>Segment deleted while waiting<br/>Response missing due to server error

NetworkError

statusCode	message	Description
1001	Network Not Connected	Network connection blocked
1002	Network Timeout	Network delay<br/>Invalid waiting room HTML URL<br/>NetFUNNEL server down

Block

statusCode	message	Description
301	Block	Segment block

IpBlock

statusCode	message	Description
302	Macro Block	Blacklist<br/>BotManager Basic enabled

Close

statusCode	message	Description
499	Canceled Waiting Room	Cancel button clicked on default waiting room
498	Closed Blocking Room	Close button clicked on block room
497	Closed Macro Blocking Room	Close button clicked on macro block room
496	Closed PreWaiting Room	Close button clicked on pre-waiting room
495	Closed PostWaiting Room	Close button clicked on post-waiting room

function nfCallback(response) {
  const { status, statusCode, message } = response;
  
  switch(status) {
    case 'Success':
      // Entry or bypass; run your existing service logic as before NetFUNNEL.
      // e.g. navigate, run function, call API
      break;
    
    case 'Error':
      // System error; usually run the same logic as Success for a smooth experience.
      // e.g. navigate, run function, call API
      break;
      
    case 'NetworkError':
      // Network error; run your logic or prompt and re-enter the queue.
      // e.g. navigate, run function, call API, modal("Network unstable. Retry? Y/N");
      break;
      
    case 'Block':
      // Entry blocked; notify or do nothing.
      break;
      
    case 'IpBlock':
      // Blocked due to repeated requests; notify or do nothing.
      break;
      
    case 'Close':
      // User closed or canceled the waiting room; notify or do nothing.
      // e.g. alert("Waiting canceled.");
      break;
      
    default:
      console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
  }
}