Version: 4.6.1-saas

Web/JavaScript Agent

Overview

The NetFUNNEL JavaScript agent is a dedicated NetFUNNEL client that communicates with the NetFUNNEL server in the web browser.

Agent Installation

Initialization

The NetFUNNEL JavaScript agent is applied to the service through initialization code when the page loads. Because it must run before service logic, it is recommended to place it at the top of the head tag.

Code

Add the initialization code to the HTML of the page where you will use the NetFUNNEL JavaScript agent.

<html>
  <head>
    ...
    <script
      src="{{AGENT_URL}}"
      data-nf-client-id="{{CLIENT_ID}}"
    ></script>
    ...
  </head>
</html>

Agent Application

There are two ways to set queue control points with the NetFUNNEL JavaScript agent: URL-triggered application and code-based application.

URL-triggered application

Applied through trigger rules in the NetFUNNEL console segment settings. When the URL of the page the user accesses matches the trigger rules, the queue is applied. Because it is configured in the NetFUNNEL console, no application redeployment is required and queue application points can be changed in real time.

Code-based application

Call the functions provided by NetFUNNEL in your application code. Redeployment is required whenever you change queue application points, but because the waiting room is shown before traffic occurs, traffic can be controlled effectively in advance.

warning

Customers who have installed the NetFUNNEL JavaScript agent can use both application methods, but for simpler configuration and easier management, use only one method.

URL-triggered application

Queue control points can be set through segment trigger rules in the NetFUNNEL console. The queue is applied when the URL of the page the user accesses is compared with the trigger rules and they match.

Operation flow

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

Configuration options

Logical Operator: When creating two or more trigger rules, determines the relationship between them using and or or operators.
Validator: Defines the top-level scope of what the trigger rule applies to. Currently only URL is provided.
Component: Specifies the target for applying rules in more detail within the scope defined by the Validator. This can be the full URL or path, and is used to apply rules to specific pages or resources.
Negate: Use when you want to apply the opposite of the set condition. For example, enable this option when you want to apply a rule when a specific condition is not 'true'.
Match: Defines the type of condition for when the rule applies. You can apply rules based on matching a specific value or when a specific condition exists through options such as 'Equals' and 'Exists'.
Value: Specifies the concrete value to compare when applying the rule. This value is used together with the 'Match' condition to determine when the rule is activated.
Aa: Determines whether to be case-sensitive when comparing with Value.

Match options

Exists: Checks whether the Component exists in the URL. (Only available when Component is Path.)
Equals: Checks whether the Component value and Value match exactly.
Contains: Checks whether the specified Value is contained in the Component value.
StartsWith: Checks whether the Component value starts with the specified Value.
EndsWith: Checks whether the Component value ends with the specified Value.

Trigger rule testing

You can test in advance to verify that the URL where you want to apply the queue matches the trigger rules.

Code-based application

Code-based application has start and end functions. Call the start function to issue a key from the NetFUNNEL server, and when waiting is complete and entry is granted, call the end function to return the key. Returning the key allows the next person in line to enter.

Operation flow

Before waiting: Page load → Agent initialization → Start function execution
During waiting: NetFUNNEL server request → NetFUNNEL key issuance → Waiting room display
After waiting: Success logic execution → End function execution

Basic control

Start function

Function name: nfStart
Description: Call the function at the point where you want to apply waiting to issue a key and display the waiting room.
Application point: Apply at page entry or at the start of an event.

Parameter	Type	Description	Required
projectKey	String	Basic control project key from NetFUNNEL console	O
segmentKey	String	Basic control segment key from NetFUNNEL console	O
callback	Function	User-defined callback function for waiting room event handling	O

nfStart({
  projectKey: "{{PROJECT_KEY}}",
  segmentKey: "{{SEGMENT_KEY}}"
}, function(response) {
  // TODO: Implement the appropriate callback function according to response.
  nfCallback(response);
});

End function

Function name: nfStop
Description: Used to return the key after entry is complete.
Application point: Apply after the start function ends or at the point where the entered user's activity is complete.

warning

If the end function is not executed, return is processed automatically according to the segment timeout setting.

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

nfStop({
  projectKey: "{{PROJECT_KEY}}",
  segmentKey: "{{SEGMENT_KEY}}"
});

Section control

Section control is a feature that keeps the number of concurrent users in a specific section of the application at a constant value. A key is issued when the start function is called, and until the end function is called, the user is considered to be in the activity section, so the next person in line is not allowed to enter. When the end function is called, the key is returned and the next person in line can enter.

Start function

Function name: nfStartSection
Description: Call the function at the point where you want to apply waiting to issue a key and display the waiting room.
Application point: Apply at page entry or at the start of an event.

Parameter	Type	Description	Required
projectKey	String	Section control project key from NetFUNNEL console	O
segmentKey	String	Section control segment key from NetFUNNEL console	O
callback	Function	User-defined callback function for waiting room event handling	O

nfStartSection({ 
  projectKey: "{{PROJECT_KEY}}", 
  segmentKey: "{{SEGMENT_KEY}}" 
}, function(response) {
  // TODO: Implement the appropriate callback function according to response.
  nfCallback(response);
});

End function

Function name: nfStopSection
Description: Used to return the key after entry is complete.
Application point: Apply at the point where the entered user's activity section ends.

warning

If the end function is not executed, the user is considered to remain in the activity section and the next person in line may be delayed from entering.

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

nfStopSection({
  projectKey: "{{PROJECT_KEY}}",
  segmentKey: "{{SEGMENT_KEY}}"
});

Callback function

Responses from the NetFUNNEL server can be received in the callback function, which is the second parameter of the start function for both basic control and section control. Users can perform various handling logic according to the response result.

info

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

Success

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

Error

statusCode	message	Description
500	Server Error	Use of non-existent project/segment key Segment deleted while waiting Response missing due to server error

NetworkError

statusCode	message	Description
1001	Network Not Connected	Network connection blocked
1002	Network Timeout	Network delay Invalid waiting room html address NetFUNNEL server down

Block

statusCode	message	Description
301	Block	Segment blocked

IpBlock

statusCode	message	Description
302	Macro Block	Blacklist BotManager Basic enabled

Close

statusCode	message	Description
499	Canceled Waiting Room	Basic waiting room cancel button clicked
498	Closed Blocking Room	Block room close button clicked
497	Closed Macro Blocking Room	Macro block room close button clicked
496	Closed PreWaiting Room	Pre-waiting room close button clicked
495	Closed PostWaiting Room	Post-waiting room close button clicked

function nfCallback(response) {
  const { status, statusCode, message } = response;
  
  switch(status) {
    case 'Success':
      // Entry or bypass response received; run existing service logic before NetFUNNEL was applied.
      // ex - page navigation, function execution, API request
      break;
    
    case 'Error':
      // System error occurred; run existing service logic the same as Success for smooth service use.
      // ex - page navigation, function execution, API request
      break;
      
    case 'NetworkError':
      // Network error occurred; run existing service logic or notify and have user re-enter the queue.
      // ex - page navigation, function execution, API request, alert("Network request failed. Retrying.");
      break;
      
    case 'Block':
      // Entry status is blocked; you may notify of block or do nothing.
      // ex - alert("This page is blocked from entry.");
      break;
      
    case 'IpBlock':
      // Blocked due to repeated requests; you may notify of block or do nothing.
      // ex - alert("You have been blocked due to repeated requests.");
      break;
      
    case 'Close':
      // Waiting room close or cancel button clicked; you may notify of wait cancellation or do nothing.
      // ex - alert("Waiting has been canceled.");
      break;
      
    default:
      console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
  }
}

Additional features

The NetFUNNEL JavaScript agent provides various additional features. To enable additional features, add configuration values to the initialization code. Available additional features differ by application method; refer to the table below.

UTI: URL-triggered application (URL Triggered Integration)
CBI: Code-based application (Code Based Integration)

Initialization code settings

data attribute	Application method	Description	Default
data-nf-network-timeout	UTI, CBI	Maximum wait time for network response	3000
data-nf-retry-count	UTI, CBI	Network retry count	0
data-nf-custom-cookie-domain	UTI, CBI	Domain setting when storing cookies	Empty
data-nf-use-network-recovery-mode	UTI, CBI	Keep waiting room and recover on network error	false
data-nf-storage-type	UTI, CBI	Browser storage selection	both
data-nf-return-key	UTI	Key return handling	true
data-nf-error-bypass	CBI	Return Success status instead of Error, NetworkError	false
data-nf-use-netfunnel-template	CBI	Use custom waiting room	true
data-nf-health-check-url	CBI	Network health check address	Empty

Overview​

Agent Installation​

Initialization​

Code​

Agent Application​

URL-triggered application​

Operation flow​

Configuration options​

Match options​

Trigger rule testing​

Code-based application​

Operation flow​

Basic control​

Section control​

Callback function​

Additional features​

Initialization code settings​

Overview

Agent Installation

Initialization

Code

Agent Application

URL-triggered application

Operation flow

Configuration options

Match options

Trigger rule testing

Code-based application

Operation flow

Basic control

Section control

Callback function

Additional features

Initialization code settings