본문으로 건너뛰기
버전: 4.6.1

초기화 옵션 참조

NetFUNNEL JavaScript 에이전트의 모든 구성 옵션(data-attributes)에 대한 완전한 참조입니다.

목차​

필수 속성​

이러한 속성은 에이전트가 올바르게 작동하기 위해 필수입니다.

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

네트워크 설정​

NetFUNNEL 서버 통신에 대한 네트워크 동작 및 타임아웃을 제어합니다.

속성방법필수기본값범위
data-nf-network-timeoutURL 트리거, 코드 기반선택 사항3000100–10000
data-nf-retry-countURL 트리거, 코드 기반선택 사항00–10
data-nf-use-network-recovery-modeURL 트리거, 코드 기반선택 사항falsetrue/false

네트워크 오류 개념​

네트워크 오류와 그 처리를 이해하는 것은 NetFUNNEL을 올바르게 구성하는 데 중요합니다. 동작은 통합 방법과 오류 원인에 따라 크게 다릅니다.

네트워크 오류 원인:

원인설명감지예제
오프라인클라이언트 측 네트워크 연결 끊김네트워크 오프라인 (navigator.onLine = false로 감지)WiFi 비활성화, 이더넷 연결 해제, 비행기 모드
지연타임아웃을 초과하는 네트워크 지연응답 시간 > data-nf-network-timeout느린 연결, 서버 과부하, 네트워크 혼잡

오류 분류:

오류 유형설명재시도 동작
일시적 오류임시 네트워크 문제 (오프라인/지연)data-nf-retry-count를 기반으로 자동 재시도
영구적 오류모든 재시도 시도 소진더 이상 재시도하지 않음, 오류 처리 트리거

통합 방법별 오류 처리:

오류 처리는 모든 재시도 시도가 소진된 후(영구적 오류) 발생합니다.

요청 → 타임아웃 → 일시적 오류 → 재시도 → 성공 또는 영구적 오류 → 오류 처리
통합 방법5101 (키 발급) 오류서비스 진입5002 (진입 확인) 오류서비스 진입
URL 트리거오류 처리 없음 (즉, 트래픽 제어 우회 → 대상 페이지)✅ 예네트워크 오류 페이지 (w/ 다시 시도 버튼)❌ 아니오
코드 기반NetworkError 콜백 (w/ 1001 또는 1002 상태 코드) -> 대기실 모달 표시 안 됨❌ 아니오NetworkError 콜백 (w/ 1001 또는 1002 상태 코드) → 대기실 모달 닫기❌ 아니오

data-nf-network-timeout​

NetFUNNEL 서버 API 요청이 일시적 오류로 간주되기 전의 최대 타임아웃 지속 시간입니다.

속성값
단위밀리초 (ms)
범위100–10000
기본값3000
적용 대상NetFUNNEL 서버 엔드포인트만

동작:

  • 타임아웃 내 응답 없음 → 일시적 오류
  • 즉시 오류 응답 → 타임아웃 대기 없음
  • 각 재시도는 동일한 타임아웃 설정을 사용합니다

예제:

  • data-nf-network-timeout="1000" → 1초 타임아웃
  • data-nf-network-timeout="5000" → 5초 타임아웃

data-nf-retry-count​

NetFUNNEL 서버 API 호출에서 일시적 오류에 대한 추가 재시도 시도 횟수입니다.

속성값
범위0–10
기본값0
공식총 시도 = (설정 값) + 1
적용 대상NetFUNNEL 서버 엔드포인트만

동작:

  • 일시적 오류 → 재시도 트리거 (재시도 횟수 > 0인 경우)
  • 영구적 오류 → 모든 재시도 시도 소진
  • 각 재시도는 data-nf-network-timeout 설정을 준수합니다

예제:

  • data-nf-retry-count="0" → 재시도 없음 (단일 시도)
  • data-nf-retry-count="1" → 초기 1회 + 재시도 1회 (총 2회 시도)
  • data-nf-retry-count="2" → 초기 1회 + 재시도 2회 (총 3회 시도)
URL 트리거 5101 예외

URL 트리거 5101 요청에는 재시도 메커니즘이 없습니다 - 단일 오류가 영구적 오류가 되어 트래픽 제어를 완전히 우회합니다.

data-nf-use-network-recovery-mode​

네트워크 문제로 인해 사용자가 대기실에서 쫓겨나는 것을 방지합니다. 활성화되면 네트워크 문제가 발생해도 사용자가 대기 상태(모달 또는 대기실)에 머물고, 연결이 복구되면 자동으로 재개됩니다.

속성값
기본값false
적용 대상5002 (진입 확인) 요청만
핵심 이점네트워크 문제 중 대기 경험 중단 없음

이것이 해결하는 문제:

  • 복구 모드 없이: 네트워크 오류 → 오류 페이지/콜백 → 사용자가 대기 위치 손실
  • 복구 모드 사용: 네트워크 오류 → 대기 상태 유지 → 네트워크 복구 시 자동 재개

동작:

모드5002 (진입 확인)사용자 경험
true대기 상태 유지, 자동 복구중단 없음
false정상 재시도 → 오류 처리오류 페이지/콜백

복구 시나리오:

  • 빠른 복구: 기존 키/시퀀스 유지 (대기 순번 유지)
  • 장기 중단: 새 키/시퀀스 가져오기 (순번이 재설정될 수 있음)
대기 순번 유지

장기 중단에 걸쳐 대기 순번 보존을 보장하려면 NetFUNNEL 콘솔의 대기 순번 유지 기능을 사용하세요.

네트워크 설정 상호 작용 흐름​

타임아웃, 재시도 횟수 및 복구 모드가 함께 작동하여 네트워크 오류를 처리하는 방법입니다.

네트워크 설정 동작​

네트워크 설정이 함께 작동하는 방식과 다양한 통합 방법 및 복구 모드에서의 결합 효과입니다.

NetFUNNEL 서버 API 엔드포인트​

API 엔드포인트목적네트워크 설정의 영향
5101 (키 발급)키 및 대기 결정에 대한 초기 요청timeout, retry-count
5002 (진입 확인)대기실에 있는 동안 주기적 요청timeout, retry-count, recovery-mode
5003 (Alive Notice)키 활성 상태 유지 (구간 제어만)timeout, retry-count
5004 (키 반환)서비스 완료 후 키 반환timeout, retry-count

네트워크 오류 유형​

코드유형설명
1001네트워크 연결 안 됨네트워크가 오프라인이거나 연결할 수 없음
1002네트워크 타임아웃요청이 타임아웃 제한을 초과함

시나리오 1: 정상 흐름 (5101 성공)

시나리오 2: 5101 (키 발급) 네트워크 오류 (재시도 없음)

시나리오 3: 5002 (진입 확인) 네트워크 오류 (재시도 포함)

시나리오 4: 복구 모드 활성화

스토리지 및 쿠키 옵션​

NetFUNNEL이 브라우저에 상태 값을 저장하는 방법을 제어합니다.

속성방법필수기본값옵션
data-nf-use-storage-typeURL 트리거, 코드 기반선택 사항bothboth, session, cookie
data-nf-custom-cookie-domainURL 트리거, 코드 기반선택 사항(비어 있음)도메인 문자열

data-nf-use-storage-type​

트래픽 제어 중에 NetFUNNEL은 키를 포함한 다양한 상태 값을 브라우저에 저장합니다. 이것은 사용되는 스토리지 유형을 지정합니다.

옵션:

  • both: 최대 호환성을 위해 sessionStorage와 쿠키 모두 사용
  • session: sessionStorage만 사용 (탭이 닫히면 데이터 손실)
  • cookie: 쿠키만 사용 (브라우저 세션 간 지속)

서브도메인 간 쿠키 공유를 위한 쿠키 도메인을 강제합니다.

사용법: 도메인 문자열(예: .example.com)을 제공하여 서브도메인 간 쿠키를 공유합니다.

URL 트리거 옵션​

URL 트리거 통합에서만 사용되는 옵션입니다.

속성방법필수기본값옵션
data-nf-return-keyURL 트리거선택 사항truetrue/false

data-nf-return-key​

URL 트리거 방법에서는 NetFUNNEL 대기실로 리디렉션된 다음 대상 페이지로 돌아갑니다. 이 속성은 진입 후 키를 자동으로 반환할지 여부를 제어합니다.

동작:

  • true (기본값): 대상 페이지로 돌아갈 때 키가 자동으로 반환됨
  • false: 수동 키 반환 필요 (사용자 정의 통합 시나리오에 유용)

UI 및 템플릿 옵션​

대기실 모양과 템플릿을 제어합니다.

속성방법필수기본값옵션
data-nf-use-netfunnel-templateURL 트리거, 코드 기반선택 사항truetrue/false

data-nf-use-netfunnel-template​

기본 NetFUNNEL 대기실 템플릿을 사용합니다.

옵션:

  • true (기본값): NetFUNNEL의 표준 대기실 템플릿 사용
  • false: 사용자 정의 대기실 템플릿 구현 허용

오류 처리 옵션​

오류가 처리되고 사용자에게 표시되는 방법을 제어합니다.

속성방법필수기본값옵션
data-nf-error-bypassURL 트리거, 코드 기반선택 사항falsetrue/false

data-nf-error-bypass​

Error/NetworkError를 Success로 처리합니다.

동작:

  • false (기본값): 정상 오류 처리 (오류 시 콜백/리디렉션)
  • true: 오류를 성공으로 처리하여 서비스가 계속되도록 허용 (우회 모드)

처리되는 오류 유형:

  • 네트워크 오류 (1001, 1002)
  • 서버 오류 (500)
  • 사용자 취소 (499)
  • 잘못된 구성 오류

URL 트리거 통합 오류 페이지: data-nf-error-bypass="false"이고 네트워크 복구 모드가 비활성화된 경우 사용자는 다음을 봅니다:

네트워크 오류
기기 또는 통신의 네트워크 오류로 인해 대기 프로세스가 중단되었습니다.

아래 버튼을 눌러 다시 대기하세요.
[다시 시도 버튼]

코드 기반 통합 콜백: data-nf-error-bypass="false"인 경우 다음 콜백이 트리거됩니다:

  • onNetworkError: 네트워크 관련 오류 (1001, 1002)
  • onError: 서버 오류 (500)
  • onClose: 사용자 취소 (499)

완전한 예제​

모든 옵션이 포함된 완전한 초기화 스크립트입니다:

<script
  src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
  data-nf-client-id="your-client-id"
  data-nf-retry-count="2"
  data-nf-network-timeout="5000"
  data-nf-use-network-recovery-mode="true"
  data-nf-use-storage-type="both"
  data-nf-custom-cookie-domain=".example.com"
  data-nf-return-key="true"
  data-nf-use-netfunnel-template="true"
  data-nf-error-bypass="false"
></script>

관련 문서​