Web Agent v.4.1.8
NetFUNNEL 에이전트는 NetFUNNEL 서버와 통신하기 위한 일종의 NetFUNNEL 전용 클라이언트 입니다. 사용자는 적용하고자 하는 클라이언트 어플리케이션 코드에 에이전트에서 제공하는 다양한 함수들을 적용, 구현하여 가상 대기실을 적용할 수 있습니다.
Web Agent 동작 흐름도
NetFUNNEL 에이전트는 크게 위와 같은 동작 흐름을 가지고 있습니다.
1. 대기 전
- 대기를 하기 전에는 설정 정보 초기화를 진행합니다. 이 과정은 NetFUNNEL 서버의 URL, Setting 파일의 URL, SDK URL을 받아서 초기화 하는 과정입니다.
- 콘솔 페이지 내 Agent → Web 메뉴에서
NetFUNNEL Tag코드를<head>최상단에 삽입하세요.
2. 대기 중
- 가상 대기실을 노출하여 트래픽 대기를 적용하고 싶은 페이지(html)의 특정 부분에 대기를 적용하는 과정입니다.
- 가상 대기실이 노출되어 주기적으로 재진입 요청을 합니다. 가상 대기실의 대기 인원과 예상 시간을 업데이트 합니다.
- SDK에서 제공되는
대기 시작 함수를 사용하여 가상 대기실을 적용하세요. - 대기 응답시 대기창이 호출되고 차단 응답시 차단창이 호출됩니다.
- 진입 허용 응답시 대기가 종료되고 콜백 함수가 호출됩니다.
3. 대기 후
- 대기가 종료된 이후의 과정입니다 대기 종료 후 넷퍼넬 서버로 진입키를 반납하여 진입이 완료되었음을 알립니다.
- 진입 성공 시 SDK에서 제공되는
완료처리 함수를 사용하여 대기 종료 후 로직을 구현하세요. - 사용자가 대기가 종료되는 이유는 아래의 3가지 경우가 있습니다.
1️⃣ 진입 성공 : 주기적으로 재진입 요청하는 도중 진입 성공 응답을 받았을 경우
2️⃣ 진입 요청 실패 : 재진입 요청시 서버에서 응답이 없거나 네트워크 에러가 발생하는 경우
3️⃣ 대기 취소 : 대기 취소 버튼을 클릭하는 경우
에이전트 적용 방법
Step 1. NetFUNNEL Tag 코드 삽입
콘솔 페이지의 Agent 메뉴의 Web 탭에서 아래의 코드를 <head> 태그의 최상단에 입력해주세요.
<script>
(function(w, d, s, uri, fn) {
w[fn] = w[fn] || function() {
var c = {};
c.tenantApiUrl = arguments[0];
c.tenantNFUrl = arguments[1];
c.tenantLoaderPort = arguments[2];
(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', '{에이전트 라이브러리 요청 주소}', 'nfTag');
nfTag('{넷퍼넬 환경정보 요청 주소}', '{넷퍼넬 서버 요청 주소}', '443');
</script>MPA(Multi-Page Application) 형태의 프로젝트에서는 각 HTML 페이지의 <head> 태그 내에 NetFUNNEL Tag 코드를 삽입해야 합니다. 예를 들어, index.html, list.html, detail.html 세 개의 페이지가 존재한다면, 각각의 <head> 태그 섹션의 최상단에 NetFUNNEL Tag 코드를 삽입해야 합니다.
중복 삽입 회피: 웹 사이트에 모든 HTML 파일에서 공통으로 참조되는 JavaScript 파일이 있다면, 그 공통 파일 내에 단 한 번만 Code Snippet을 삽입하여 중복 작업을 회피할 수 있습니다.
Step 2. API 호출을 통한 트래픽 제어
소스 코드에 API 형태로 대기창 기능을 활성화할 수 있습니다.
projectKey : 트래픽 제어를 할 프로젝트의 키입니다. 콘솔의 사이드바에서 복사 가능합니다.
segmentKey : 트래픽 제어를 할 세그먼트의 키입니다. 콘솔의 기본 제어/구간제어 탭에서 복사 가능합니다.
1) 기본 제어
기본 제어 시작 함수
- 함수명 :
NFStart - 적용 위치 : 페이지로 진입하는 부분의 코드에 적용합니다.
- 설명 : 가상 대기실을 노출하여 트래픽 대기를 적용하고 싶은 페이지(html)에 적용할 수 있습니다.
- 종료 시점 : 함수의 콜백함수가 호출되면 종료됩니다. 이 때 진입 대상페이지가 로드될 때 일반대기 종료함수
NFStop를 사용하여 키를 반납하여야 합니다. - Parameter : 콘솔의 기본제어 탭에서 세그먼트를 생성 후 해당 키를 API Parameter에 입력 합니다.
/*
* @param {object} projectKey, segmentKey
* @param {Function} success callback
*/
NFStart({
projectKey: '{프로젝트 키}',
segmentKey: '{세그먼트 키}'
}, function(response){
// TODO : 페이지 이동을 위한 로직을 구현합니다.
// Example : window.location.href = '{기본대기 후 진입 URL}';
});기본 제어 시작 샘플 코드
다음은 메인 페이지로 이동하기 위한 로그인 페이지의 일반 대기 적용 예시 코드입니다.
▶️ AS-IS : NetFUNNEL 적용 전의 로그인 페이지 코드 예시입니다.
<!DOCTYPE html>
<html>
<head>
<title>로그인 페이지</title>
</head>
<body>
<h1>로그인</h1>
<form id="loginForm">
<label for="username">사용자 이름:</label>
<input type="text" id="username" name="username" />
<label for="password">비밀번호:</label>
<input type="password" id="password" name="password" />
<button type="submit">로그인</button>
</form>
<script>
function loginAPI(id, pwd) {
// 로그인 API 로직 구현
return true;
}
document.getElementById("loginForm").addEventListener("submit", function (event) {
event.preventDefault();
var username = document.getElementById("username").value;
var password = document.getElementById("password").value;
var result = loginAPI(username, password);
if (result) {
// 로그인 성공 시 메인페이지로 이동
location.href = "/main";
} else {
alert("login Failed");
}
});
</script>
</body>
</html>▶️TO-BE : NetFUNNEL 적용 후의 로그인 페이지 예시입니다.
<!DOCTYPE html>
<html>
<head>
<!-- NetFUNNEL Tag 코드 삽입 -->
<script>
(function (w, d, s, uri, fn) {
w[fn] =
w[fn] ||
function () {
var c = {};
c.tenantApiUrl = arguments[0];
c.tenantNFUrl = arguments[1];
c.tenantLoaderPort = arguments[2];
(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", "{에이전트 라이브러리 요청 주소}", "nfTag");
nfTag("{넷퍼넬 환경정보 요청 주소}", "{넷퍼넬 서버 요청 주소}", "443");
</script>
<title>로그인 페이지</title>
</head>
<body>
<h1>로그인</h1>
<form id="loginForm">
<label for="username">사용자 이름:</label>
<input type="text" id="username" name="username" />
<label for="password">비밀번호:</label>
<input type="password" id="password" name="password" />
<button type="submit">로그인</button>
</form>
<script>
function loginAPI(id, pwd) {
// 로그인 API 로직 구현
return true;
}
document.getElementById("loginForm").addEventListener("submit", function (event) {
event.preventDefault();
var username = document.getElementById("username").value;
var password = document.getElementById("password").value;
var result = loginAPI(username, password);
if (result == true) {
// 로그인 성공 시 NetFUNNEL 대기를 거쳐서 메인페이지로 이동
NFStart(
{
projectKey: "service_34",
segmentKey: "segKey_2555",
},
function () {
window.location.href = "/main";
}
);
} else {
alert("login Failed");
}
});
</script>
</body>
</html>2) 구간 제어
구간 제어 시작 함수
- 함수명 :
NFStartSection - 적용 위치 : 구간 제어의 시작 페이지로 진입하는 부분
- 설명 : 가상 대기실을 노출하여 페이지의 구간(시작페이지 ~ 종료페이지)에 머무는 트래픽에 대한 대기를 적용하고 싶은 시작 페이지(html)에 적용할 수 있습니다.
- 종료 시점 : 함구간대기 종료함수
NFStopSection를 사용하여 키를 반납하는 페이지에서 종료됩니다. - Parameter : 콘솔의 구간제어 탭에서 세그먼트를 생성 후 해당 키를 API Parameter에 입력 합니다.
/*
* @param {object} projectKey, segmentKey
* @param {Function} success callback
*/
NFStartSection({
projectKey: '{프로젝트 키}',
segmentKey: '{세그먼트 키}'
}, function(response){
// TODO : 구간대기의 시작페이지로 이동하는 로직을 구현합니다.
// Example : window.location.href = '{구간대기 후 Start URL}';
});부록
1. 기본 제어(일반 대기)
단일 페이지의 서비스 유입을 제어하며, 일반대기 세그먼트에 등록된 URL에 대해 초당 진입량을 제어할 수 있습니다.
- 고정형 : 처리 시간과 관계없이 고정 된 진입 허용 수로 조절합니다.
- 다이내믹 : 최소 진입 허용수와 최대 진입 허용 수를 따로 설정하여 기준 구간 처리 시간에 따라 진입 허용 수를 자동으로 조절합니다.
2. 구간 제어(구간 대기)
지정된 페이지 사이의 유입을 제어하며, 구간대기 세그먼트에 등록된 시작, 종료 URL을 확인하여 해당 구간 내 머무르는 사용자 수(진입량)을 제어할 수 있습니다.
3. EUM(End User Monitoring)
NetFUNNEL을 통해 진입되는 사용자에 대해서는 EUM 데이터가 수집되어 콘솔을 통해 모니터링 할 수 있습니다.
4. 메인 페이지 제어
사용자들이 가장 먼저 접하게 되는 메인 페이지 폭주에 대한 해결법으로 가장 좋은 방법은 메인 페이지를 가볍게 변경하는 것입니다. 외부에서 바로 메인 페이지 접근이 아닌, NetFUNNEL 대기 페이지를 기존 메인 페이지 대신 적용하여 메인 페이지 자체에 대한 진입량을 제어할 수 있습니다. 구간대기 적용시에도 마찬가지로 구간대기 진입 페이지에 동일하게 적용 가능합니다.
- 동작 흐름 : NetFUNNEL 대기 페이지 (index.html) → 기존 메인 페이지 (index_real.html)
💡 메인 페이지 제어 적용 방법
Step 1
기존의 메인 페이지였던 index.html 을 index_real.html로 변경하고, NetFUNNEL 대기 페이지로 이용할 HTML 파일을 index.html로 적용해주세요.
Step 2
index.html 내 tag Code Snippet을 삽입하여 Agent를 설치해주세요.
Step 3
load 이벤트의 콜백함수로 NFStart API를 호출해주세요.
Step 4
callback(function) - 필수
아래의 적용 예시를 참고하여 기존 메인 페이지의 URL로 이동하는 코드를 작성해주세요.
Step 5
localStorage 또는 sessionStorage 또는 Cookie를 사용하여 실제 페이지의 URL이 노출 되었을 때 악의적으로 직접 접근하는 행위를 막기 위해 대기페이지index.html을 거쳐서 진입했을 때만 실제페이지index_real.html을 사용할 수 있도록 추가하는 방식을 사용할 수 있습니다.
소스 코드 내 API 적용 예시
대기 페이지
<!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>NetFUNNEL 대기 페이지</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', '{에이전트 라이브러리 요청 주소}', 'nfTag');
nfTag('{테넌트 정보 요청 URL}', '{넷퍼넬 서버 요청 URL}');
// 페이지 로드 시 대기 시작
window.addEventListener('load', function() {
NFStart({
projectKey: 'service_1',
segmentKey: 'segKey_1'
}, function(response) {
localStorage.setItem('passedThroughWaiting', 'true'); // 대기 페이지를 거친 것으로 표시
location.href = 'index_real.html'; // 실제 메인 페이지로 이동
});
});
</script>
</head>
<body>
<h1>대기 페이지</h1>
<!-- 대기 페이지 내용 -->
</body>
</html>