Version: 4.6.1

API Reference

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

Basic Control Functions
Section Control Functions
Callback Function
Response Object Schema
Status Codes Reference
Best Practices

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 at the beginning of an action.

Function Signature:

nfStart(keys, callback)

Parameters:

Parameter	Type	Description	Required
`keys`	Object	Object containing project and segment keys	Yes
`keys.projectKey`	String	Basic Control project key from the console	Yes
`keys.segmentKey`	String	Basic Control segment key from the console	Yes
`callback`	Function	User-defined callback to handle VWR events	Yes

Returns: undefined

Example:

nfStart({
  projectKey: "service_1",
  segmentKey: "segKey_8612"
}, function(response) {
  // Handle the response - see Callback Function section for details
  if (response.status === 'Success') {
    // Proceed with your logic
    console.log('Entry granted!');
  }
});

Callback Handling: See Callback Function section for detailed response handling.

nfStop

Purpose: Return the key after entry is completed.

Function Signature:

nfStop(keys)

Parameters:

Parameter	Type	Description	Required
`keys`	Object	Object containing project and segment keys	Yes
`keys.projectKey`	String	Basic Control project key from the console	Yes
`keys.segmentKey`	String	Basic Control segment key from the console	Yes

Returns: undefined

Example:

nfStop({
  projectKey: "service_1",
  segmentKey: "segKey_8612"
});

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 keeps the number of concurrent users within a specific application section at a fixed value. 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.

nfStartSection

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

Function Signature:

nfStartSection(keys, callback)

Parameters:

Parameter	Type	Description	Required
`keys`	Object	Object containing project and segment keys	Yes
`keys.projectKey`	String	Section Control project key from the console	Yes
`keys.segmentKey`	String	Section Control segment key from the console	Yes
`callback`	Function	User-defined callback to handle VWR events	Yes

Returns: undefined

Example:

nfStartSection({
  projectKey: "service_1",
  segmentKey: "section_segKey_1234"
}, function(response) {
  // Handle the response - see Callback Function section for details
  if (response.status === 'Success') {
    // User entered the section
    console.log('Section entry granted!');
  }
});

Callback Handling: See Callback Function section for detailed response handling.

nfStopSection

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

Function Signature:

nfStopSection(keys)

Parameters:

Parameter	Type	Description	Required
`keys`	Object	Object containing project and segment keys	Yes
`keys.projectKey`	String	Section Control project key from the console	Yes
`keys.segmentKey`	String	Section Control segment key from the console	Yes

Returns: undefined

Example:

nfStopSection({
  projectKey: "service_1",
  segmentKey: "section_segKey_1234"
});

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 Function

You can receive responses from the NetFUNNEL server in the callback function (the second parameter) of the Basic/Section Control start functions (nfStart and nfStartSection). Based on the response result, you can perform various handling logic.

Required Status Handling

You must handle these three statuses:

Success: Entry granted or bypass mode
Error: System error occurred
NetworkError: Network connection issues

Sample Callback Implementation

function nfCallback(response) {
  const { status, statusCode, message } = response;
  
  switch (status) {
    case 'Success':
      // Entry or bypass received — run the original service logic
      console.log('User can proceed!');
      // e.g., navigate to a page, run a function, call an API
      break;
      
    case 'Error':
      // A system error occurred — for smooth UX, run the original logic
      console.log(`System error: ${message}`);
      // e.g., navigate to a page, run a function, call an API
      break;
      
    case 'NetworkError':
      // A network error occurred — retry with recursive calling
      console.log(`Network error: ${message}`);
      // Recursive call to retry the NetFUNNEL start function
      nfStart(keys, nfCallback); // or nfStartSection(keys, nfCallback)
      break;
      
    case 'Block':
      // Entry state is Block — notify the user
      console.log('Access blocked');
      // e.g., alert("This page is blocked for entry.");
      break;
      
    case 'IpBlock':
      // Blocked due to repeated requests
      console.log('IP blocked');
      // e.g., alert("You have been blocked due to repeated requests.");
      break;
      
    case 'Close':
      // User clicked close/cancel in the waiting room
      console.log('Waiting canceled by user');
      // e.g., alert("Waiting has been canceled.");
      break;
      
    default:
      console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
  }
}

Response Object Schema

The response object delivered to the callback includes 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 Codes Reference

Complete reference for all possible status codes and their meanings.

Status	StatusCode	Message	Description
Success	200	`Success`	Successfully passed the queue and entered the service
	300	`Bypass`	Subscription/license expired, project/segment deactivated, `data-nf-error-bypass=true`
	303	`Express`	Express entry succeeded
Error	500	`Server Error`	Using a non-existent key, segment deleted while waiting, server error
NetworkError	1001	`Network Not Connected`	Network connection blocked
	1002	`Network Timeout`	Network latency, invalid waiting-room HTML, server down
Block	301	`Block`	Segment is in block state
IpBlock	302	`Macro Block`	Blacklist, BotManager Basic enabled
Close	499	`Canceled Waiting Room`	Clicked the cancel/close button in the standard waiting room
	498	`Closed Blocking Room`	Closed the blocking room
	497	`Closed Macro Blocking Room`	Closed the macro blocking room
	496	`Closed PreWaiting Room`	Closed the pre-waiting room
	495	`Closed PostWaiting Room`	Closed the post-waiting room

Best Practices

Function Availability Check

Always check if NetFUNNEL functions are available before calling them:

if (typeof window.nfStart === 'function') {
  nfStart(keys, callback);
} else {
  // Fallback logic
  console.log('NetFUNNEL not available, proceeding without protection');
  performOriginalLogic();
}

Key Matching

Start and stop functions must use identical keys:

const keys = { 
  projectKey: 'service_1', 
  segmentKey: 'segKey_8612' 
};

// Start
nfStart(keys, callback);

// Stop (must use same keys)
nfStop(keys);

Key Return Strategy

Return keys only when user successfully enters:

function performAction() {
  nfStart(keys, function(response) {
    if (response.status === 'Success') {
      doSomething();
    }
  });
}

// Return key when page loads (for page navigation cases)
window.addEventListener('load', () => {
  if (typeof window.nfStop === 'function') {
    nfStop(keys);
  }
});

Common Integration Patterns

Button Click Protection

document.getElementById('login-button').addEventListener('click', () => {
  if (typeof window.nfStart === 'function') {
    nfStart({
      projectKey: 'service_1',
      segmentKey: 'login_segKey'
    }, function(response) {
      // See Callback Function section for detailed response handling
      if (response.status === 'Success') {
        performLogin();
      } else {
        handleError(response);
      }
    });
  } else {
    performLogin(); // Fallback
  }
});

function performLogin() {
  // Your login logic here
  fetch('/api/login', { /* ... */ })
    .then(() => {
      // Return key after successful login
      if (typeof window.nfStop === 'function') {
        nfStop({
          projectKey: 'service_1',
          segmentKey: 'login_segKey'
        });
      }
    })
    .catch(() => {
      // Return key even on error
      if (typeof window.nfStop === 'function') {
        nfStop({
          projectKey: 'service_1',
          segmentKey: 'login_segKey'
        });
      }
    });
}

NetworkError Handling with Recursive Calling

For NetworkError status, you should implement recursive calling to retry the NetFUNNEL start function. This ensures better user experience when network issues are temporary.

// Basic Control with NetworkError recursive calling
function startWithRetry(keys) {
  nfStart(keys, function(response) {
    switch (response.status) {
      case 'Success':
        // Proceed with original logic
        performAction();
        break;
        
      case 'NetworkError':
        console.log('Network error, retrying...');
        // Recursive call to retry
        startWithRetry(keys);
        break;
        
      case 'Error':
        console.log('System error, proceeding without protection');
        performAction();
        break;
        
      default:
        console.log(`Unexpected status: ${response.status}`);
        performAction();
    }
  });
}

// Section Control with NetworkError recursive calling
function startSectionWithRetry(keys) {
  nfStartSection(keys, function(response) {
    switch (response.status) {
      case 'Success':
        // User entered the section
        showCheckoutForm();
        break;
        
      case 'NetworkError':
        console.log('Network error, retrying section entry...');
        // Recursive call to retry
        startSectionWithRetry(keys);
        break;
        
      case 'Error':
        console.log('System error, proceeding without section protection');
        showCheckoutForm();
        break;
        
      default:
        console.log(`Unexpected status: ${response.status}`);
        showCheckoutForm();
    }
  });
}

// Usage example
const keys = {
  projectKey: 'service_1',
  segmentKey: 'segKey_8612'
};

// Start with retry logic
startWithRetry(keys);

function performAction() {
  // Your business logic here
  console.log('Performing protected action...');
  
  // Return key when action completes
  nfStop(keys);
}

function showCheckoutForm() {
  // Your checkout form logic here
  console.log('Showing checkout form...');
}

Multi-step Section Control

// Start section (e.g., checkout process)
function startCheckout() {
  nfStartSection({
    projectKey: 'service_1',
    segmentKey: 'checkout_segKey'
  }, function(response) {
    // See Callback Function section for detailed response handling
    if (response.status === 'Success') {
      showCheckoutForm();
    }
  });
}

// End section (e.g., after payment completion)
function completeCheckout() {
  // Your checkout completion logic
  processPayment()
    .then(() => {
      // Return key after successful completion
      nfStopSection({
        projectKey: 'service_1',
        segmentKey: 'checkout_segKey'
      });
    });
}

Code-based Integration: Implementation guide with examples
Initialization Option Reference: All data-attribute options
Troubleshooting: Common issues and solutions

Table of Contents​

Basic Control Functions​

nfStart​

nfStop​

Section Control Functions​

nfStartSection​

nfStopSection​

Callback Function​

Required Status Handling​

Sample Callback Implementation​

Response Object Schema​

Status Codes Reference​

Best Practices​

Function Availability Check​

Key Matching​

Key Return Strategy​

Common Integration Patterns​

Button Click Protection​

NetworkError Handling with Recursive Calling​

Multi-step Section Control​

Related Documentation​

Table of Contents

Basic Control Functions

nfStart

nfStop

Section Control Functions

nfStartSection

nfStopSection

Callback Function

Required Status Handling

Sample Callback Implementation

Response Object Schema

Status Codes Reference

Best Practices

Function Availability Check

Key Matching

Key Return Strategy

Common Integration Patterns

Button Click Protection

NetworkError Handling with Recursive Calling

Multi-step Section Control

Related Documentation