For Developers
Web Agent

23min
This document is following the new released update on Surffy (v23.07.1).
﻿
﻿
Web
This document provides a guide to applying and integrating Surffy NetFUNNEL Agent in the web environment.
Installation
You can install Surffy NetFUNNEL Agent by simply copying and pasting.
Copy the Code Snippet from the agent menu in the console
Insert the copied Code Snippet into HTML
That snippet can be found below.
Paste the Code Snippet between the <head> and </head> tags in the HTML of your domain, including your main domain.
If your website is using multiple HTML, you must put a code snippet in each HTML.
(If there is a JS file commonly used in all HTML, enter it only once in the common file and use it.)
Snippet
HTML
<script>
    (function(w,d,s,uri,fn){
      w[fn] = w[fn] || function(){ var c = {}; c.tenantApiUrl = arguments[0]; c.tenantNFUrl = arguments[1]; (w[fn].l = w[fn].l || []).push(c); };
      var o = d.createElement(s); var p = d.getElementsByTagName(s)[0]; o.async = 1; o.charset = 'utf-8'; o.src = uri; p.parentNode.insertBefore(o,p);
      })(window,document,'script','<https://agent-lib.surffy-dev.io/surffy-agent_latest.js','nfTag>');
    nfTag('<https://surffy-demo.surffy.io/nf-setting.json>', '<https://surffy-demo.surffy.io>');
</script>
<script>
    (function(w,d,s,uri,fn){
      w[fn] = w[fn] || function(){ var c = {}; c.tenantApiUrl = arguments[0]; c.tenantNFUrl = arguments[1]; (w[fn].l = w[fn].l || []).push(c); };
      var o = d.createElement(s); var p = d.getElementsByTagName(s)[0]; o.async = 1; o.charset = 'utf-8'; o.src = uri; p.parentNode.insertBefore(o,p);
      })(window,document,'script','<https://agent-lib.surffy-dev.io/surffy-agent_latest.js','nfTag>');
    nfTag('<https://surffy-demo.surffy.io/nf-setting.json>', '<https://surffy-demo.surffy.io>');
</script>
﻿
﻿
Snippet example
HTML
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>List</title>

  <!-- surffy tagCode -->
  <script>
    (function(w,d,s,uri,fn){
      w[fn] = w[fn] || function(){ var c = {}; c.tenantApiUrl = arguments[0]; c.tenantNFUrl = arguments[1]; (w[fn].l = w[fn].l || []).push(c); };
      var o = d.createElement(s); var p = d.getElementsByTagName(s)[0]; o.async = 1; o.charset = 'utf-8'; o.src = uri; p.parentNode.insertBefore(o,p);
      })(window,document,'script','{request address for agent library}','nfTag');
    nfTag('{request URL for tenant info}','{request URL for netfunnel server}');
  </script>
	
  <!-- project code -->
  </head>
  <body>
  ...
  
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>List</title>

  <!-- surffy tagCode -->
  <script>
    (function(w,d,s,uri,fn){
      w[fn] = w[fn] || function(){ var c = {}; c.tenantApiUrl = arguments[0]; c.tenantNFUrl = arguments[1]; (w[fn].l = w[fn].l || []).push(c); };
      var o = d.createElement(s); var p = d.getElementsByTagName(s)[0]; o.async = 1; o.charset = 'utf-8'; o.src = uri; p.parentNode.insertBefore(o,p);
      })(window,document,'script','{request address for agent library}','nfTag');
    nfTag('{request URL for tenant info}','{request URL for netfunnel server}');
  </script>
	
  <!-- project code -->
  </head>
  <body>
  ...
  
﻿
Basic dynamic traffic control is completed when snippet is applied as above, and if you want control through direct API call or control when visiting the main page, please refer here. 
﻿
Web Agent Operation Flow
When the agent is installed in the user's browser, preparation for communication with NetFUNNEL is completed and operates in the following flow. 
﻿
Function
NetFUNNEL Agent minimizes the insertion of additional code in the customer's source code and dynamically supports the waiting window function by monitoring the URL in the segment.
Multi-domain
You can control the traffic of multiple sites of your customers individually on one platform.
If you want to individually manage three domains, promotion.com, platform.com, and reserve.com, create a project for each main domain.
URL-based dynamic traffic control
﻿﻿You can control traffic in real time without modifying the source code of the customer by registering URLs that need to be controlled into segments.﻿﻿
The URL can be controlled by checking whether the Query Parameter matches.
When checking the query parameters, if the URL entered in the segment is http://test.com/main and the URL to be applied is http://test.com/main?key=value, NetFUNNEL isn't applied because it is recognized as a different URL. If you want to apply it to URLs including query parameters, please enter the entire string to be the same.
﻿
﻿Basic Control﻿
It controls the service inflow of a single page and can control the amount of inflow per second for URLs registered in the Basic control segment.
Default control segment type
Static: Adjusts by a static limited inflow regardless of the processing time.
Dynamic: By separately setting the minimum limited inflow and the maximum limited inflow, adjusts automatically the limited inflow according to processing time per section.
﻿
﻿Path Control﻿
You can control the inflow between selected pages, and you can control the inflow in the section by checking the start and end URLs registered in the section control segment.
﻿
﻿EUM﻿
For users entering through NetFUNNEL, EUM data is collected and can be monitored through the console.
Beacon API is used to collect EUM data, and therefore support is not available when using IE browser.
﻿
Requirements
Regardless of the underlying website implementation tool and framework, support is available if you communicate and turn pages in the ways below.
Using Ajax communication based on XHR
Page transition through HTML pure <a> Tag
﻿
Applicable Control Method
1) Basic Dynamic Traffic Control
The waiting room function can be activated based on segment information without additional source code modification.
Ajax communication using XHR:
Ajax communication library based on XHR can also support it. (jQuery ajax, Axios)
When switching pages through HTML pure a Tag:
A pure a tag is judged to be an a tag that does not include '#' in the URL to be moved and does not have an onClickEvent.
﻿
2) Control through direct API call
When you want to directly use the waiting room function arbitrarily, such as applying to a method that requires traffic control without using the basic dynamic traffic control, you can activate the waiting room function in the form of an API in the source code.
Surffy_Action(request URL, callback)
As an entry request API, it is used to activate the waiting room.
When the function is executed, the Surffy NetFUNNEL server is requested to issue a ticket. Apply the corresponding API to methods that require traffic control.
HTML
Surffy_Action({entered URL in Segment}, function() {
	// to do
});
Surffy_Action({entered URL in Segment}, function() {
	// to do
});
﻿
Parameter
url(string) *required
This is the URL to be subject of traffic control. If it matches the URL registered in the Surffy console, it requests access to the Surffy NetFUNNEL server. Otherwise, the callback function passed as the second argument is executed immediately.
callback(function) *optional
A callback function that is executed when an entry response code is received from the surffy NetFUNNEL Web Agent. Even if the URL does not correspond to the segment URL registered in the console, the callback function is executed immediately.
﻿
API application example in source code
HTML
<script>
    const handleSubmitForm = (e) => {
      e.preventDefault();
      console.log("submit");

    // Logic such as validation
    if (document.test.userid.value == "") {
      ...
      return false;
    }
    
    // use method
    Surffy_Action(document.test.action, () => {
      document.test.submit();
    });
  };
</script>

<form name="test" action="/test" onsubmit="return handleSubmitForm(event)">
  <input type="text" name="userid" />
  <input type="submit" value="login" />
</form>
<script>
    const handleSubmitForm = (e) => {
      e.preventDefault();
      console.log("submit");

    // Logic such as validation
    if (document.test.userid.value == "") {
      ...
      return false;
    }
    
    // use method
    Surffy_Action(document.test.action, () => {
      document.test.submit();
    });
  };
</script>

<form name="test" action="/test" onsubmit="return handleSubmitForm(event)">
  <input type="text" name="userid" />
  <input type="submit" value="login" />
</form>
﻿
HTML
...
<script>
  const handleClickButton = () => {
    // Logic before method execution
		if (!validation()) {
      return false;
    }

		// use method
    Surffy_Action('https://surffy.io/button', function() {
      console.log('callback');
    });
  }
</script>

<div onclick="handleClickButton">
  <span>Please click here.</span>
</div>
...
<script>
  const handleClickButton = () => {
    // Logic before method execution
		if (!validation()) {
      return false;
    }

		// use method
    Surffy_Action('https://surffy.io/button', function() {
      console.log('callback');
    });
  }
</script>

<div onclick="handleClickButton">
  <span>Please click here.</span>
</div>
﻿
﻿
Surffy_Complete(request URL, callback)
Entry completion request API, used to end the queuing and return the ticket.
If you successfully enter after waiting normally, the ticket will be returned automatically when the page is refreshed. Therefore, it is not used unless it is a specific exceptional situation, but in other cases (using a SPA framework that does not refresh even when changing pages, etc.), you must call the corresponding function to handle completion separately.

If the ticket is not returned, the ticket is automatically returned only after the Timeout time set in the NetFUNNEL server has passed.

Therefore, in order to prevent a delay in new user entry during the timeout period, it is necessary to return the ticket when the entry response code is received.
You can call without parameters when basic control completion is requested.
HTML
Surffy_Complete();
Surffy_Complete();
﻿
﻿
You can call with parameters when requesting the completion of path control.
HTML
Surffy_Complete({enterd URL in Segment}, function() {
	//TO Do 
});
Surffy_Complete({enterd URL in Segment}, function() {
	//TO Do 
});
﻿
﻿
Parameter
url(string) *required
This is the URL to be subject for processing entry completion. If it matches the path control end URL registered in the Surffy console, it requests entry completion to the Surffy NetFUNNEL server and executes the callback function passed as the second argument.
callback(function) *optional
This is a callback function to be executed after completion request. Even if the URL does not correspond to the path control segment start URL registered in the console, the callback function is executed immediately.
﻿
API application example in source code
HTML
import React, { useEffect } from "react";

const Promotion = () => {
  useEffect(() => {
    window.Surffy_Complete();
  }, []);

  return <div>promotion page</div>;
};

export default Promotion;
import React, { useEffect } from "react";

const Promotion = () => {
  useEffect(() => {
    window.Surffy_Complete();
  }, []);

  return <div>promotion page</div>;
};

export default Promotion;
﻿
﻿
3) Main page Control
The best solution to the main page's traffic congestion that users encounter first is to lightly change the main page.
Instead of directly accessing the main page from the outside, you can control the inflow to the main page itself by applying the NetFUNNEL waiting page instead of the existing main page.
It operates in the flow of external → NetFUNNEL waiting page (index.html) → existing main page (index_real.html).
﻿
Application method
Change index.html, which was the existing main page, to index_real.html, and apply the HTML file to be used as the NetFUNNEL waiting page to index.html.
Install the Agent by inserting the tag Code Snippet in index.html.
Call the Surffy_Action API as the callback function of the load event.
﻿
Parameter
url(string) *required
This is the URL to be subject for processing entry completion. If it matches the URL registered in the Surffy console, it requests entry to the Surffy NetFUNNEL server. Otherwise, the callback function passed as the second argument is executed immediately.
callback(function) *optional
Please refer to the application example below and write a code that moves to the URL of the existing main page.
﻿
API application example in source code
HTML
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>List</title>
    <script>
	    (function(w,d,s,uri,fn){
      w[fn] = w[fn] || function(){ var c = {}; c.tenantApiUrl = arguments[0]; c.tenantNFUrl = arguments[1]; (w[fn].l = w[fn].l || []).push(c); };
      var o = d.createElement(s); var p = d.getElementsByTagName(s)[0]; o.async = 1; o.charset = 'utf-8'; o.src = uri; p.parentNode.insertBefore(o,p);
      })(window,document,'script','https://agent-lib.surffy-dev.io/surffy-agent_latest.js','nfTag');
	    nfTag('https://surffy-demo.surffy.io/nf-setting.json', 'https://surffy-demo.surffy.io');

      window.addEventListener('load',
        function() {
          // eslint-disable-next-line no-undef
          Surffy_Action('https://surffy.io/main', function() {
            location.href = 'https://surffy.io/main';
          })
        }
      );
    </script>
    
  </head>
  <body>
	...
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>List</title>
    <script>
	    (function(w,d,s,uri,fn){
      w[fn] = w[fn] || function(){ var c = {}; c.tenantApiUrl = arguments[0]; c.tenantNFUrl = arguments[1]; (w[fn].l = w[fn].l || []).push(c); };
      var o = d.createElement(s); var p = d.getElementsByTagName(s)[0]; o.async = 1; o.charset = 'utf-8'; o.src = uri; p.parentNode.insertBefore(o,p);
      })(window,document,'script','https://agent-lib.surffy-dev.io/surffy-agent_latest.js','nfTag');
	    nfTag('https://surffy-demo.surffy.io/nf-setting.json', 'https://surffy-demo.surffy.io');

      window.addEventListener('load',
        function() {
          // eslint-disable-next-line no-undef
          Surffy_Action('https://surffy.io/main', function() {
            location.href = 'https://surffy.io/main';
          })
        }
      );
    </script>
    
  </head>
  <body>
	...
﻿
﻿
Agent application Test method
If you want to check if NetFUNNEL Web Agent has been successfully applied, follow the steps below.
Set the limited inflow of basic control segment to '0'
Request to enter the web page according to the applied method (basic dynamic traffic control/API direct call/main page)
Check if the waiting room (page) appears on the screen (check VWR)
Check if there is a change in the value of the corresponding segment within the basic control of the Surffy NetFUNNEL console (check EUM)
﻿
﻿
﻿
﻿
🏄‍♂️ Any other questions or feedback on Surffy docs? E-mail us at support@stclab.com.
﻿