Web Agent

28min
﻿
Web이 문서는 Web 환경에서의 Surffy NetFUNNEL Agent 적용 및 연동 가이드를 제공합니다.
설치Copy & Paste만으로 간편하게  Surffy NetFUNNEL Agent를 설치할 수 있습니다.
콘솔 내 에이전트 메뉴에서 Code Snippet 복사
복사한 Code Snippet을 HTML 내 삽입
메인 도메인을 포함한 도메인의 HTML에서 <head>태그와 </head>태그 사이에 Code Snippet을 붙여 넣으세요.
웹 사이트에서 복수의 HTML을 사용하고 있다면, 각 HTML에 모두 Code Snippet을 입력해야 합니다. 
(모든 HTML에서 공통으로 사용하는 js파일이 있다면 공통 파일에 한 번만 입력해 사용합니다.)
﻿
SnippetHTML
|
<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','{에이전트 라이브러리 요청 주소}','nfTag');
    nfTag('{테넌트 정보 요청 URL}','{넷퍼넬 서버 요청 URL}');
  </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','{에이전트 라이브러리 요청 주소}','nfTag');
    nfTag('{테넌트 정보 요청 URL}','{넷퍼넬 서버 요청 URL}');
  </script>
	
  <!-- project code -->
  </head>
  <body>
  ...
  
﻿
위와 같이 Snippet 적용 시에 기본 동적 트래픽 제어는 완료되며, API 직접 호출을 통한 제어 혹은 메인 페이지 접근 시 제어를 원할 경우 여기를 참고해 주세요.

Web Agent 동작 흐름도사용자의 브라우저에 Agent가 설치되면 NetFUNNEL과의 통신 준비는 완료되며 아래와 같은 흐름으로 동작합니다.
﻿
기능NetFUNNEL Agent는 고객의 소스 코드 내 별도의 추가 코드 삽입을 최소화하고, 세그먼트 내 URL을 모니터링하여 동적으로 대기창 기능을 지원합니다.
멀티 도메인하나의 플랫폼에서 고객사의 여러 사이트를 개별로 트래픽 제어할 수 있습니다.
만약 promotion.com, platform.com, reserve.com 3개의 도메인에 대해서 개별적으로 관리하고 싶다면, 각 메인 도메인별로 프로젝트를 생성합니다. 
URL 기반 동적 트래픽 제어﻿제어가 필요한 URL을 세그먼트(Segment)에 등록하여 고객사의 소스 코드 수정 없이 실시간으로 트래픽 제어가 가능합니다.﻿
URL은 Query Parameter의 일치 여부까지 확인해 제어할 수 있습니다.
Query Parameter 확인 시 세그먼트 내 입력된 URL이 http://test.com/main이고, 적용하고자 하는 URL은 http://test.com/main?key=value이라면, 다른 URL로 인식하기 때문에 NetFUNNEL이 적용되지 않습니다. Query Parameter를 포함하는 URL에 적용을 원한다면 전체 문자열이 일치하도록 입력해 주세요.
 
﻿기본 제어﻿
단일 페이지의 서비스 유입을 제어하며, 기본 제어 세그먼트에 등록된 URL에 대해 초당 진입량을 제어할 수 있습니다.
기본 제어 세그먼트 유형
고정형: 처리 시간과 관계없이 고정된 진입 허용 수로 조절합니다. 
다이내믹: 최소 진입 허용 수와 최대 진입 허용 수를 따로 설정하여 기준 구간 처리 시간에 따라 진입 허용 수를 자동으로 조절합니다.
﻿
﻿구간 제어﻿
지정된 페이지 사이의 유입을 제어하며, 구간 제어 세그먼트에 등록된 시작, 종료 URL을 확인하여 해당 구간 내 머무르는 사용자 수(진입량)을 제어할 수 있습니다.
 
﻿EUM﻿
NetFUNNEL을 통해 진입되는 사용자에 대해서는 EUM 데이터가 수집되어 콘솔을 통해 모니터링 할 수 있습니다.
EUM 데이터 수집을 위하여 Beacon API를 사용하고 있으며, 이에 따라 IE 브라우저 사용 시 지원이 불가합니다.
﻿
기본 요구 사양기본 웹 사이트 구현 툴 및 프레임워크와 관계없이 아래의 방식으로 통신하고 페이지를 전환하는 경우 지원이 가능합니다.
XHR을 기반으로 한 Ajax 통신 사용
HTML 순수 <a> Tag를 통한 페이지 전환
 
적용 가능한 제어 방식1) 기본 동적 트래픽 제어별도의 소스 코드 수정 없이 세그먼트 정보를 기반으로 대기창 기능을 활성화할 수 있습니다. 
XHR을 사용한 Ajax 통신 시
XHR을 기반으로 하는 Ajax 통신 라이브러리에서도 지원 가능합니다. (jQuery ajax, Axios)
HTML 순수 <a> Tag를 통한 페이지 전환 시
순수 <a> 태그란 이동할 URL에 '#'이 포함되어 있지 않고, onClickEvent가 없는 <a> 태그일 경우로 판단합니다.
 
2) API 직접 호출을 통한 제어기본 동적 트래픽 제어를 사용하지 않고, 트래픽 제어가 필요한 메서드에 적용 등 임의로 대기창 기능을 직접 사용하고 싶을 때 소스 코드에 API 형태로 대기창 기능을 활성화할 수 있습니다.
Surffy_Action(request URL, callback)
진입 요청 API로, 대기창 활성화를 위해 사용합니다.
해당 함수 실행 시 Surffy NetFUNNEL 서버에 티켓 발급을 요청합니다. 트래픽 제어가 필요한 메서드에 해당 API를 적용합니다.
HTML
|
Surffy_Action({세그먼트 내 입력된 URL}, function() {
	// to do
});
Surffy_Action({세그먼트 내 입력된 URL}, function() {
	// to do
});
﻿
Parameter
url(string) *필수
트래픽 제어 대상이 되는 URL입니다. Surffy 콘솔에서 등록한 URL과 일치할 경우 Surffy NetFUNNEL 서버에 진입을 요청하고, 그렇지 않으면 바로 이어서 두 번째 인자로 전달한 콜백 함수를 실행합니다.

callback(function) *선택
surffy NetFUNNEL Web Agent에서 진입 응답 코드를 받았을 경우 실행하는 콜백 함수입니다. URL이 콘솔에 등록한 세그먼트 URL에 해당되지 않는 경우에도 바로 콜백 함수가 실행됩니다.
﻿
소스 코드 내 API 적용 예시
HTML
|
<script>
    const handleSubmitForm = (e) => {
      e.preventDefault();
      console.log("submit");

    // 유효성 검사 등의 로직
    if (document.test.userid.value == "") {
      ...
      return false;
    }
    
    // 메서드 사용
    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="로그인" />
</form>

<script>
    const handleSubmitForm = (e) => {
      e.preventDefault();
      console.log("submit");

    // 유효성 검사 등의 로직
    if (document.test.userid.value == "") {
      ...
      return false;
    }
    
    // 메서드 사용
    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="로그인" />
</form>
﻿
HTML
|
...
<script>
  const handleClickButton = () => {
    // 메서드 실행 전 로직
		if (!validation()) {
      return false;
    }

		// 메서드 사용
    Surffy_Action('https://surffy.io/button', function() {
      console.log('callback');
    });
  }
</script>

<div onclick="handleClickButton">
  <span>이곳을 클릭해 주세요.</span>
</div>

...
<script>
  const handleClickButton = () => {
    // 메서드 실행 전 로직
		if (!validation()) {
      return false;
    }

		// 메서드 사용
    Surffy_Action('https://surffy.io/button', function() {
      console.log('callback');
    });
  }
</script>

<div onclick="handleClickButton">
  <span>이곳을 클릭해 주세요.</span>
</div>
﻿
﻿
Surffy_Complete(request URL, callback)
진입 완료 요청 API로, 대기를 종료하고 티켓을 반납하기 위해 사용합니다.
정상적으로 대기 후 진입에 성공한 경우에는 페이지가 새로고침되면 자동으로 티켓 반납을 수행합니다. 따라서 특정 예외 상황이 아니라면 사용하지 않지만, 그렇지 못한 경우에는(페이지 전환 시에도 새로고침 되지 않는 SPA 프레임워크 사용 등), 해당 함수를 호출하여 별도로 완료 처리를 해주어야 합니다.
티켓을 반납하지 않으면 NetFUNNEL 서버에 설정된 Timeout 시간이 지나야만 자동으로 티켓이 반납됩니다.
따라서, Timeout 시간 동안 사용자의 신규 진입이 지체되는 문제를 방지하기 위해서는 진입 응답 코드를 받은 경우 티켓 반납 처리가 필요합니다.
기본 제어 완료 요청 시 파라미터 없이 호출합니다.
HTML
|
Surffy_Complete();
Surffy_Complete();
﻿
﻿
구간 제어 완료 요청 시 파라미터를 넣어 호출합니다.
HTML
|
Surffy_Complete({세그먼트 내 입력된 URL}, function() {
	//TO Do 
});
Surffy_Complete({세그먼트 내 입력된 URL}, function() {
	//TO Do 
});
﻿
Parameter
url(string) *필수
진입 완료 처리 대상이 되는 URL입니다. Surffy 콘솔에서 등록한 구간 제어 종료 URL과 일치할 경우 Surffy NetFUNNEL 서버에 진입 완료를 요청하고, 두 번째 인자로 전달한 콜백 함수를 실행합니다.

callback(function) *선택
완료 요청 후 실행하는 콜백 함수입니다. URL이 콘솔에 등록한 구간 제어 세그먼트 시작 URL에 해당되지 않는 경우에도 바로 콜백 함수가 실행됩니다.
﻿
소스 코드 내 API 적용 예시
HTML
|
import React, { useEffect } from "react";

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

  return <div>프로모션 페이지</div>;
};

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

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

  return <div>프로모션 페이지</div>;
};

export default Promotion;
﻿
﻿
3) 메인 페이지 제어사용자들이 가장 먼저 접하게 되는 메인 페이지 폭주에 대한 해결법으로 가장 좋은 방법은 메인 페이지를 가볍게 변경하는 것입니다.
외부에서 바로 메인 페이지 접근이 아닌, NetFUNNEL 대기 페이지를 기존 메인 페이지 대신 적용해 메인 페이지 자체에 대한 진입량을 제어할 수 있습니다.
외부 → NetFUNNEL 대기 페이지 (index.html) → 기존 메인 페이지 (index_real.html)의 흐름으로 동작합니다.
 
적용 방법
기존의 메인 페이지였던 index.html 을 index_real.html로 변경하고, NetFUNNEL 대기 페이지로 이용할 HTML 파일을 index.html로 적용해 주세요.
index.html 내 tag Code Snippet을 삽입하여 Agent를 설치해 주세요.
load 이벤트의 콜백 함수로 Surffy_Action API를 호출해 주세요.


Parameter
url(string) *필수
트래픽 제어 대상이 되는 URL입니다. Surffy 콘솔에서 등록한 URL과 일치할 경우 Surffy NetFUNNEL 서버에 진입을 요청하고, 그렇지 않으면 바로 이어서 두 번째 인자로 전달한 콜백 함수를 실행합니다.

callback(function) *필수
아래의 적용 예시를 참고하여 기존 메인 페이지의 URL로 이동하는 코드를 작성해 주세요.
﻿
소스 코드 내 API 적용 예시
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 적용 테스트 방법NetFUNNEL Web Agent가 잘 적용되었는지 확인하고 싶다면, 아래의 순서를 따라 진행해 주세요.
기본 제어 세그먼트의 진입 허용량을 '0'으로 설정
적용한 방식(기본 동적 트래픽 제어/API 직접 호출/메인 페이지)에 따라서 웹 페이지 내 진입 요청
대기창이 화면에 뜨는지 확인 (VWR 확인)
Surffy NetFUNNEL 콘솔 기본 제어 내 해당 세그먼트의 수치 변동이 있는지 확인 (EUM 확인)
﻿
﻿
﻿
﻿
🏄‍♂️ 기술 문서에 질문이나 피드백이 있으신가요? support@stclab.com로 문의주시면 답변드리겠습니다.
﻿