Skip to main content

JavaScript 네트워크 에러 대응 가이드

이 문서는 NetFUNNEL JavaScript 에이전트 사용 중 발생할 수 있는 네트워크 에러를 식별하고, 상황에 맞는 처리 방법과 우회 옵션, 복구 기능을 설정하는 방법을 안내합니다. 코드 기반 적용 시에 사용할 수 있는 기능입니다.

info

이 문서에서 제공하는 기능은 코드 기반 적용 시 사용할 수 있습니다.

1. 네트워크 에러 콜백

NetFUNNEL JavaScript 에이전트는 네트워크 에러 발생 시 콜백 함수에서 NetworkError 상태값을 반환합니다.

1.1 네트워크 에러 종류

NetworkError 상태값은 대기 시작 전, 또는 대기 중 네트워크 문제가 발생할 경우 호출됩니다.

statusstatusCodemessage설명
NetworkError1001Network Not Connected

네트워크 연결 차단

NetworkError1002Network Timeout

네트워크 응답 지연으로 인한 시간 초과

1.2 네트워크 에러 콜백 예시

네트워크 에러 발생 시 사용자에게 네트워크 에러 발생을 안내하고 넷퍼넬 서버로의 요청을 재시도합니다.

function nfCallback(response) {
  const { status, statusCode, message } = response;

  switch (status) {
    case 'Success':
      // Handle success
      break;

    case 'NetworkError':
      // Notify network error and retry
      alert('Network request failed, retrying.');
      nfStart(
        {
          projectKey: '{{PROJECT_KEY}}',
          segmentKey: '{{SEGMENT_KEY}}',
        },
        nfCallback
      );
      break;
  }
}

2. 네트워크 관련 설정

NetFUNNEL JavaScript 에이전트는 네트워크 환경에 유연하게 대응하기 위한 설정들을 제공합니다.

2.1 retry-count

retry-count는 네트워크 요청 실패 시, 자동으로 재시도하는 횟수입니다.

항목내용
목적

일시적 네트워크 오류에 대한 자동 재시도

기본값 (회)

0

최솟값 (회)

0

최댓값 (회)

10

동작 방식

retry-count 횟수만큼 내부 재시도 후, 실패 시 NetworkError 상태값 반환

info

data-nf-retry-count="3"로 설정하면 최초 요청 실패 시 최대 3회까지 추가로 재시도합니다. 요청이 중간에 성공하면 재시도는 중단됩니다.

<html>
  <head>
    <script src="{{AGENT_URL}}" data-nf-retry-count="0" data-nf-client-id="{CLIENT_ID}"></script>
  </head>
</html>

2.2 network-timeout

network-timeout은 네트워크 응답을 기다리는 최대 시간을 설정합니다. 응답이 지정된 시간 내에 도착하지 않으면 retry-count만큼 시도합니다.

항목내용
목적

요청 지연 또는 서버 무응답 상황을 빠르게 탐지

기본값 (ms)

3000

최솟값 (ms)

100

최댓값 (ms)

10000

동작 방식

network-timeout만큼 네트워크 응답을 기다린 후, 네트워크 실패 결정

info

data-nf-network-timeout="3000"로 설정하면 35ms 내 오류 응답이 오더라도 2.965초 뒤 재시도합니다.

tip

data-nf-network-timeout=3000, data-nf-retry-count=3 로 설정 시 네트워크 요청에 최대 12초가 소요됩니다.

warning

너무 짧은 값으로 설정할 경우, 정상적인 요청도 타임아웃으로 처리될 수 있습니다.

<html>
  <head>
    <script src="{{AGENT_URL}}" data-nf-network-timeout="3000" data-nf-client-id="{CLIENT_ID}"></script>
  </head>
</html>

2.3 health-check-url

health-check-url은 네트워크 에러 발생 시, 설정된 URL로 Health Check를 수행하여 단순 네트워크 지연인지, NetFUNNEL 서버 장애인지 구분합니다.

항목내용
기본값null
설명
  • Health Check 성공 시, 1002 상태값 반환
  • Health Check 실패 시, 1001 상태값 반환
<html>
  <head>
    <script src="{{AGENT_URL}}" data-nf-health-check-url="{{HEALTH_CHECK_URL}}" data-nf-client-id="{CLIENT_ID}"></script>
  </head>
</html>

3. 우회 관련 설정

3.1 error-bypass

error-bypass는 네트워크 요청을 실패하더라도 NetworkError 대신 Success 상태값을 반환하여, 서비스 진입을 허용합니다.

항목내용
기본값false
예시
  • 테스트 환경
  • 네트워크 연결 여부가 서비스 핵심 흐름에 영향을 주지 않는 경우. (예: 단순 이벤트 참여 등)
info

data-nf-error-bypass=true 설정 시 Error와 NetworkError 대신 Success 상태값이 반환되기 때문에 필수 구현해야 하는 상태값은 Success가 유일합니다.

warning

data-nf-error-bypass=true 설정은 모든 에러 상황을 우회 처리하므로, 사용 시 주의가 필요합니다.

<html>
  <head>
    <script src="{{AGENT_URL}}" data-nf-error-bypass="false" data-nf-client-id="{CLIENT_ID}"></script>
  </head>
</html>

4. 복구 관련 설정

4.1 use-network-recovery-mode

use-network-recovery-mode는 대기 중 네트워크 요청이 실패해도 대기실을 유지하며, 지속적으로 네트워크 연결을 시도합니다.

항목내용
기본값

false

참고

data-nf-use-network-recovery-mode=true 설정은 대기 중 네트워크가 끊긴 경우에만 대기실을 유지합니다.

info

URL 트리거 적용의 경우 network-recovery-mode가 기본적으로 동작합니다.

<html>
  <head>
    <script src="{{AGENT_URL}}" data-nf-use-network-recovery-mode="false" data-nf-client-id="{CLIENT_ID}"></script>
  </head>
</html>

5.1 일반적인 환경

<script src="{{AGENT_URL}}" data-nf-client-id="{CLIENT_ID}" data-nf-retry-count="3" data-nf-network-timeout="5000" data-nf-use-network-recovery-mode="true"></script>

5.2 불안정한 네트워크 환경

<script src="{{AGENT_URL}}" data-nf-client-id="{CLIENT_ID}" data-nf-retry-count="5" data-nf-network-timeout="10000" data-nf-use-network-recovery-mode="true"></script>

5.3 테스트 환경

<script src="{{AGENT_URL}}" data-nf-client-id="{CLIENT_ID}" data-nf-error-bypass="true" data-nf-retry-count="1" data-nf-network-timeout="3000"></script>

6. 트러블슈팅

네트워크 에러 대응 과정에서 자주 발생하는 문제들과 해결 방법을 안내합니다.

Q: 네트워크 에러가 자주 발생합니다.

A: 다음 사항을 확인하세요:

  1. data-nf-retry-count="3" 설정으로 재시도 횟수 증가

  2. data-nf-network-timeout="5000" 설정으로 타임아웃 연장

  3. 브라우저 콘솔에서 네트워크 탭 확인

  4. data-nf-health-check-url 설정으로 장애 원인 분석

Q: 대기 중 네트워크가 끊어지면 대기실이 사라집니다.

A: data-nf-use-network-recovery-mode="true" 설정을 추가하세요. 이 설정은 대기 중 네트워크가 끊긴 경우에만 대기실을 유지합니다.

Q: 1001과 1002 에러의 차이점이 무엇인가요?

A: 두 에러의 차이점은 다음과 같습니다:

  1. 1001 (Network Not Connected): 브라우저의 네트워크 연결 자체가 차단된 상태

  2. 1002 (Network Timeout): 네트워크는 연결되어 있으나 응답이 지연되는 상태

  3. 1001의 경우 즉시 사용자에게 네트워크 확인 안내 필요

  4. 1002의 경우 재시도 로직 또는 대기 안내 권장

Q: 테스트 환경에서 네트워크 에러로 인해 테스트가 어렵습니다.

A: 테스트 환경 설정 방법:

  1. data-nf-error-bypass="true" 설정으로 모든 에러를 성공으로 처리

  2. 개발자 도구 Network 탭에서 'Offline' 모드로 1001 에러 테스트

  3. data-nf-network-timeout="100" 설정으로 1002 에러 테스트

  4. 각 상황별 콜백 함수 동작 확인

Q: 브라우저별로 네트워크 동작이 다릅니다.

A: 브라우저별 대응 방법:

  1. Chrome: 적극적인 캐싱 정책으로 인한 네트워크 지연 가능

  2. Safari: 엄격한 보안 정책으로 인한 요청 차단 가능

  3. Firefox: 추적 방지 기능으로 인한 스크립트 차단 가능

  4. 각 브라우저의 개발자 도구에서 네트워크 상태 확인 필요

Q: HTTPS 환경에서만 에러가 발생합니다.

A: HTTPS 환경 문제 해결:

  1. Mixed Content 정책으로 인한 HTTP 요청 차단 확인

  2. SSL 인증서 문제로 인한 네트워크 차단 확인

  3. CSP(Content Security Policy) 설정 확인

  4. 브라우저 보안 설정 및 확장 프로그램 영향 확인