Version: 4.6.1-saas

API Reference

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

Basic Control Functions

Basic control limits the entry rate to a 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.

Netfunnel.nfStart

Purpose: Issues a key and displays the waiting room when an operation starts.

Function Signature:

Netfunnel.nfStart(projectKey, segmentKey, callback)

Parameters:

Parameter	Type	Description
`projectKey`	String	Basic control project key from console
`segmentKey`	String	Basic control segment key from console
`callback`	Function	Custom callback function for waiting room event handling

Return Value: undefined

Example:

Netfunnel.nfStart("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", function(response) {
  // Handle response - refer to callback function section
  nfCallback(response);
});

Callback Handling: For detailed response handling, refer to the Callback Functions section.

Netfunnel.nfStop

Purpose: Returns the key after entry is completed.

Function Signature:

Netfunnel.nfStop(projectKey, segmentKey)

Parameters:

Parameter	Type	Description
`projectKey`	String	Basic control project key from console
`segmentKey`	String	Basic control segment key from console

Return Value: undefined

Example:

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

Automatic Return Timeout

If the stop function is not executed, the key is automatically returned according to the segment timeout setting (default timeout: 20 seconds).

Section Control Functions

Section control maintains the concurrent user count within a specific application section at a fixed value. When the start function is called, a key is issued. The user is considered to be in an active section until the stop function is called, and the next user in the queue is not allowed.

Netfunnel.nfStartSection

Purpose: Issues a key for section control and displays the waiting room.

Function Signature:

Netfunnel.nfStartSection(projectKey, segmentKey, callback)

Parameters:

Parameter	Type	Description
`projectKey`	String	Section control project key from console
`segmentKey`	String	Section control segment key from console
`callback`	Function	Custom callback function for waiting room event handling

Return Value: undefined

Example:

Netfunnel.nfStartSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", function(response) {
  // Handle response - refer to callback function section
  nfCallback(response);
});

Callback Handling: For detailed response handling, refer to the Callback Functions section.

Netfunnel.nfStopSection

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

Function Signature:

Netfunnel.nfStopSection(projectKey, segmentKey)

Parameters:

Parameter	Type	Description
`projectKey`	String	Section control project key from console
`segmentKey`	String	Section control segment key from console

Return Value: undefined

Example:

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

Section Control Behavior

If the stop function is not executed, the user is considered to remain in the active section, and the next user's allowance may be delayed.

Callback Functions

You can receive responses from the NetFUNNEL server in the callback function (third parameter) of the basic/section control start function. You can perform various processing logic based on the response result.

Required Status Handling

The following three statuses must be handled:

Success: Entry allowed or bypass mode
Error: System error occurred
NetworkError: Network connection problem

note

Status values other than Success, Error, and NetworkError do not need to be handled and will not affect the service.

Sample Callback Implementation

function nfCallback(response) {
  const { status, statusCode, message } = response;
  switch(status) {
    case 'Success':
      // When entry or bypass response is received, execute existing service logic before applying NetFUNNEL.
      // ex - page navigation, function execution, API request
      break;
    case 'Error':
      // When system error occurs, generally execute existing service logic the same as Success for smooth service use.
      // ex - page navigation, function execution, API request
      break;
    case 'NetworkError':
      // When network error occurs, execute existing service logic or prompt to re-enter the queue after notification.
      // ex - page navigation, function execution, API request, modal("Network is unstable. Would you like to retry? Y/N");
      break;
    case 'Block':
      // When entry status is blocked, you can notify the blocking or do nothing.
      break;
    case 'IpBlock':
      // When blocked due to repeated requests, you can notify the blocking or do nothing.
      break;
    case 'Close':
      // When the close or cancel button of the waiting room is clicked, you can notify the cancellation or do nothing.
      // ex - alert("Waiting has been canceled.");
      break;
    default:
      console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
  }
}

Response Object Schema

The response object passed to the callback contains the following fields:

Field	Type	Example / Description
`status`	String	`Success` / `Error` / `NetworkError` / `Block` / `IpBlock` / `Close`
`statusCode`	Number	200, 201, 300, 303, 500, 1001, 1002, 301, 302, 49x, etc.
`message`	String	`Success`, `Bypass`, `Express`, `Server Error`, `Network Timeout`, etc.
`key`	String	Issued entry key (ID)

Example Response Objects:

// Success response
{
  status: "Success",
  statusCode: 200,
  message: "Success",
  key: "key_12345"
}

// Bypass response
{
  status: "Success", 
  statusCode: 300,
  message: "Bypass",
  key: "key_12345"
}

// Network error response
{
  status: "NetworkError",
  statusCode: 1002,
  message: "Network Timeout",
  key: "key_12345"
}

Status Code Reference

Complete reference for all possible status codes and their meanings.

status	statusCode	message	Description
Success	200	Success	Entry to service after normal queue passage
	300	Bypass	Subscription/license expired Project/segment deactivated Set data-nf-error-bypass=true
	303	Express	Behavior on successful entry
Error	500	Server Error	Using non-existent project/segment key Segment deleted while waiting Response missing due to server error
NetworkError	1002	Network Timeout	Network delay Invalid waiting room HTML address NetFUNNEL server down
Block	301	Block	Segment blocked
IpBlock	302	Macro Block	Blacklist BotManager Basic activated
Close	499	Canceled Waiting Room	Cancel button clicked in default waiting room
	498	Closed Blocking Room	Close button clicked in blocking room
	497	Closed Macro Blocking Room	Close button clicked in macro blocking room
	496	Closed PreWaiting Room	Close button clicked in pre-waiting room
	495	Closed PostWaiting Room	Close button clicked in post-waiting room

Best Practices

Centralized Configuration

// Store keys in one place
const NETFUNNEL_CONFIG = {
  projectKey: 'service_1',
  segmentKey: 'segKey_8612'
};

// Use the same configuration everywhere
Netfunnel.nfStart(
  NETFUNNEL_CONFIG.projectKey,
  NETFUNNEL_CONFIG.segmentKey,
  callback
);

Netfunnel.nfStop(
  NETFUNNEL_CONFIG.projectKey,
  NETFUNNEL_CONFIG.segmentKey
);

Complete Error Handling

function handleNetFunnelResponse(response, businessLogic) {
  switch (response.status) {
    case 'Success':
      businessLogic(); // Proceed with logic
      break;
    case 'Error':
      // System error - continue to maintain service execution
      console.error('NetFUNNEL system error:', response.message);
      businessLogic();
      break;
    case 'NetworkError':
      // Network problem - continue or retry
      console.log(`NetFUNNEL network error: ${response.message}`);
      businessLogic(); // Continue or implement retry logic
      break;
    case 'Block':
      Alert.alert('Service Unavailable', 'This service is temporarily unavailable.');
      break;
    case 'IpBlock':
      Alert.alert('Access Denied', 'If this problem persists, please contact support.');
      break;
    case 'Close':
      // User canceled - no action needed
      break;
  }
}

Key Return

// Return key after successful operation
try {
  await performAction();
  Netfunnel.nfStop(projectKey, segmentKey);
} catch (error) {
  console.error('Operation failed:', error);
  // Return key even on error
  Netfunnel.nfStop(projectKey, segmentKey);
}

Basic Control Method: Basic control implementation guide
Section Control Method: Section control implementation guide
Initialization Options Reference: All initialization parameters
Troubleshooting: Common issues and solutions

Basic Control Functions​

Netfunnel.nfStart​

Netfunnel.nfStop​

Section Control Functions​

Netfunnel.nfStartSection​

Netfunnel.nfStopSection​

Callback Functions​

Required Status Handling​

Sample Callback Implementation​

Response Object Schema​

Status Code Reference​

Best Practices​

Centralized Configuration​

Complete Error Handling​

Key Return​

Related Documentation​

Basic Control Functions

Netfunnel.nfStart

Netfunnel.nfStop

Section Control Functions

Netfunnel.nfStartSection

Netfunnel.nfStopSection

Callback Functions

Required Status Handling

Sample Callback Implementation

Response Object Schema

Status Code Reference

Best Practices

Centralized Configuration

Complete Error Handling

Key Return

Related Documentation