버전: 4.6.1

설치 및 초기화

이 가이드는 URL 트리거 통합과 코드 기반 통합 방법 모두에 적용되는 필수 설정 단계를 다룹니다.

1단계: 초기화 코드 가져오기

프로덕션 코드 필요

아래 코드는 예제일 뿐입니다. NetFUNNEL 콘솔의 전용 초기화 코드를 반드시 사용해야 합니다.

실제 초기화 코드를 가져오는 방법:

NetFUNNEL 콘솔로 이동
상단의 에이전트 메뉴 클릭
클라이언트 측 에이전트 → JavaScript로 이동
2. 설치 방법 섹션에서 프로젝트별 코드 복사

Agent initialization script placement

콘솔 vs. 문서

NetFUNNEL 콘솔에서는 초기화 스크립트에 data-nf-client-id가 표시됩니다. 모든 사용 가능한 속성의 전체 목록은 이 문서를 참조하세요.

예제 초기화 코드:

<script
    src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
    data-nf-client-id="your-client-id"
></script>

필수 속성

초기화 스크립트에는 다음 필수 속성이 필요합니다:

속성	설명	필수
`data-nf-client-id`	클라이언트 식별자	예

전체 속성 참조

선택적 네트워크 설정, 스토리지 옵션, 디버깅 기능을 포함한 모든 사용 가능한 속성에 대한 자세한 정보는 초기화 옵션 참조를 참조하세요.

2단계: 모든 HTML 파일에 적용

방법 A: 직접 HTML 삽입 (권장)

최대 신뢰성과 성능을 위해 초기화 스크립트를 각 HTML 파일에 직접 적용합니다.

중요: 먼저 로드되어야 함

NetFUNNEL 에이전트는 페이지 로드 시 다른 모든 것보다 먼저 실행되어야 합니다. 모든 HTML 파일의 <head> 맨 위에 배치하세요.

이것이 중요한 이유:

트래픽 제어는 스크립트가 로드된 페이지에만 적용됩니다
에이전트는 다른 스크립트가 실행되기 전에 요청을 가로채야 합니다
이 단계를 놓치면 = 우회 모드 (대기실 보호 없음)

중요한 타이밍 요구 사항:

NetFUNNEL 스크립트에 defer 또는 async 속성을 사용하지 마세요
스크립트는 동기적으로 즉시 실행되어야 합니다

오류 처리 필요

중요: 사용자가 트래픽 제어를 우회하는 것을 방지하기 위해 항상 오류 처리를 구현하세요. 자세한 구현은 오류 처리 - 방법 A 섹션을 참조하세요.

일반적인 위치:

메인 페이지 (index.html)
랜딩 페이지
SPA 진입점
오류 페이지 (보호하려는 경우)

여러 페이지 예제:

<!-- main/index.html -->
<head>
  <script
      src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
      data-nf-client-id="your-client-id"
  ></script>
  <!-- 다른 head 요소 -->
</head>

<!-- landing/index.html -->  
<head>
  <script
      src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
      data-nf-client-id="your-client-id"
  ></script>
  <!-- 다른 head 요소 -->
</head>

방법 B: 동적 스크립트 주입 (대안)

많은 HTML 파일이 있고 NetFUNNEL 초기화를 중앙화하려면 공통 JavaScript 파일을 통해 동적 스크립트 주입을 사용할 수 있습니다.

중요: 먼저 로드되어야 함

동적 주입을 사용하더라도 NetFUNNEL 스크립트는 여전히 페이지에서 실행되는 첫 번째 스크립트여야 합니다. 공통 JavaScript 파일이 다른 모든 스크립트보다 먼저 로드되도록 하세요.

이것이 중요한 이유:

트래픽 제어는 스크립트가 로드된 페이지에만 적용됩니다
에이전트는 다른 스크립트가 실행되기 전에 요청을 가로채야 합니다
이 단계를 놓치면 = 우회 모드 (대기실 보호 없음)

중요한 타이밍 요구 사항:

첫 번째 위치를 보장하기 위해 insertBefore(script, head.firstChild) 사용
NetFUNNEL 스크립트에 defer 또는 async 속성을 사용하지 마세요
스크립트는 동기적으로 즉시 실행되어야 합니다

오류 처리 필요

중요: 사용자가 트래픽 제어를 우회하는 것을 방지하기 위해 항상 오류 처리를 구현하세요. 자세한 구현은 오류 처리 - 방법 B 섹션을 참조하세요.

1단계: 공통 JavaScript 파일 생성

프로젝트에 netfunnel-init.js(또는 유사한 이름) 파일을 생성합니다:

// netfunnel-init.js
(function() {
  // NetFUNNEL이 이미 로드되었는지 확인
  if (window.NetFUNNEL || document.querySelector('script[data-nf-client-id]')) {
    return;
  }

  // NetFUNNEL 스크립트 요소 생성 및 구성
  var scriptNF = document.createElement("script");
  
  // 필수 속성 설정
  scriptNF.setAttribute("data-nf-client-id", "your-client-id");
  scriptNF.setAttribute("data-nf-retry-count", "0");
  scriptNF.setAttribute("data-nf-network-timeout", "3000");
  
  // 스크립트 소스 설정
  scriptNF.src = "https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js";
  
  // head의 시작 부분에 스크립트 삽입
  var head = document.head || document.getElementsByTagName('head')[0];
  head.insertBefore(scriptNF, head.firstChild);
})();

2단계: HTML 파일에 공통 스크립트 포함

<html>
  <head>
    <!-- NetFUNNEL 초기화가 먼저여야 함 -->
    <script src="./netfunnel-init.js"></script>
    <!-- 다른 스크립트 -->
    <script src="./app.js"></script>
    <script src="./analytics.js"></script>
  </head>
  <body>...</body>
</html>

검증: 사용된 방법에 관계없이 항상 다음을 확인하세요:

NetFUNNEL 스크립트가 먼저 로드됨 (네트워크 탭 확인)
netfunnel-javascript-agent.js와 nf-setting.json 모두 HTTP 200 반환
초기화 중 JavaScript 오류가 발생하지 않음

3단계: 설치 확인

NetFUNNEL 에이전트를 구현한 후 다음을 확인하여 올바르게 작동하는지 확인하세요:

필수 파일 로딩

다음 파일이 HTTP 200으로 로드되는지 확인:

netfunnel-javascript-agent.js - 메인 에이전트 파일
nf-setting.json - 구성 파일

브라우저 DevTools 확인

1단계: 브라우저 DevTools 열기

F12를 누르거나 우클릭 → "검사"
네트워크 탭으로 이동

2단계: 네트워크 탭 구성

"로그 보존" 또는 "로그 유지" 활성화 (페이지 탐색 후에도 로그 유지)
"캐시 비활성화" 활성화 (새로운 요청 보장)
기존 네트워크 로그 지우기

3단계: 페이지 다시 로드

페이지 새로고침 (Ctrl+F5 또는 Cmd+Shift+R)
네트워크 탭에서 다음 파일 확인:

파일	예상 상태	목적
`netfunnel-javascript-agent.js`	200 OK	메인 NetFUNNEL 에이전트 스크립트
`nf-setting.json`	200 OK	에이전트 구성 설정

오류 처리

오류 처리는 보안을 유지하고 사용자가 트래픽 제어를 우회하는 것을 방지하는 데 중요합니다. NetFUNNEL 에이전트가 로드에 실패하면 사용자는 우회를 허용하는 대신 오류 페이지로 리디렉션되어야 합니다.

오류 처리가 중요한 이유:

보안: 사용자가 NetFUNNEL 스크립트를 차단하여 트래픽 제어를 우회하는 것을 방지
사용자 경험: 에이전트 로드 실패 시 명확한 피드백 제공
준수: 트래픽 제어 정책이 일관되게 적용되도록 보장

방법 A: 직접 HTML 삽입 NetFUNNEL 스크립트 태그에 onerror 속성을 직접 추가합니다:

<script
    src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
    data-nf-client-id="your-client-id"
    onerror="(function () { window.location.href='/your-custom-error-page.html' })()"
></script>

방법 B: 동적 스크립트 주입 스크립트 생성에 오류 처리 추가:

// netfunnel-init.js
(function() {
  if (window.NetFUNNEL || document.querySelector('script[data-nf-client-id]')) {
    return;
  }

  var scriptNF = document.createElement("script");
  scriptNF.setAttribute("data-nf-client-id", "your-client-id");
  // ... 다른 속성들
  
  scriptNF.src = "https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js";
  
  // 오류 처리
  scriptNF.onerror = function() {
    console.error('NetFUNNEL 에이전트 로드 실패');
    // 다음 옵션 중 하나를 선택:
    window.location.href = "/your-custom-error-page.html";  // 사용자 정의 오류 페이지
    // window.location.href = "/";  // 홈페이지로 리디렉션
    // document.body.innerHTML = '<div>서비스를 일시적으로 사용할 수 없습니다</div>';  // 메시지 표시
  };

  scriptNF.onload = function() {
    console.log('NetFUNNEL 에이전트가 성공적으로 로드되었습니다');
  };
  
  document.head.insertBefore(scriptNF, document.head.firstChild);
})();

오류 처리 옵션

모든 방법은 다음 오류 처리 전략을 지원합니다:

사용자 정의 오류 페이지: window.location.href='/your-custom-error-page.html'
메인 페이지 리디렉션: window.location.href='/' (홈페이지로 리디렉션)
서비스 사용 불가 페이지: window.location.href='/service-unavailable.html'
사용자 정의 메시지: document.body.innerHTML='<div>서비스를 일시적으로 사용할 수 없습니다</div>'

애플리케이션의 오류 처리 전략에 가장 적합한 옵션을 선택하세요.

문제 해결

스크립트가 로드되지 않음:

src URL이 올바른지 확인
NetFUNNEL 서버에 대한 네트워크 연결 확인
광고 차단기가 간섭하지 않는지 확인

우회 모드 (대기실 없음):

data-nf-client-id가 있는지 확인
콘솔에서 세그먼트가 활성화되었는지 확인
진입 허용 수가 무제한으로 설정되지 않았는지 확인

스크립트 배치 문제:

스크립트를 <head>의 맨 위로 이동
defer 또는 async 속성 제거
NetFUNNEL보다 먼저 실행되는 다른 스크립트가 없는지 확인

1단계: 초기화 코드 가져오기​

필수 속성​

2단계: 모든 HTML 파일에 적용​

방법 A: 직접 HTML 삽입 (권장)​

방법 B: 동적 스크립트 주입 (대안)​

3단계: 설치 확인​

필수 파일 로딩​

브라우저 DevTools 확인​

오류 처리​

오류 처리 옵션​

문제 해결​