문제 해결 & FAQ
NetFUNNEL JavaScript 에이전트 통합에 대한 일반적인 문제, 해결 방법 및 자주 묻는 질문입니다.
목차
설치 문제
에이전트 스크립트가 로드되지 않음
증상:
- Network 탭에
netfunnel-javascript-agent.js가 없음 - 에이전트 파일에 대한 HTTP 404 또는 기타 오류
해결 방법:
- 스크립트 URL 확인:
srcURL이 올바르고 접근 가능한지 확인 - 네트워크 연결: 서버가 NetFUNNEL 서버에 연결할 수 있는지 확인
- 광고 차단기: 스크립트를 차단할 수 있는 광고 차단기 비활성화
- 스크립트 배치: 스크립트를
<head>태그의 최상단으로 이동
<!-- 올바른 배치 -->
<head>
<script src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js" data-nf-client-id="your-client-id"></script>
<!-- 기타 스크립트 -->
</head>
설정 파일이 로드되지 않음
증상:
- Network 탭에
nf-setting.json이 없음 - 설정 파일에 대한 HTTP 오류
해결 방법:
data-nf-client-id확인: 클라이언트 ID가 올바른지 확인- 콘솔 액세스: NetFUNNEL 콘솔에 적절한 액세스 권한이 있는지 확인
- 세그먼트 활성화: 콘솔에서 세그먼트가 활성화되어 있는지 확인
우회 모드 (대기실 없음)
증상:
- 사용자가 대기실 없이 페이지에 직접 액세스
- NetFUNNEL 트래픽 제어 없음
해결 방법:
- 필수 속성:
data-nf-client-id가 있는지 확인 - 세그먼트 활성화: 콘솔에서 세그먼트가 활성화되어 있는지 확인
- 진입 허용 수: 진입 허용 수가 무제한으로 설정되지 않았는지 확인
- 트리거 규칙: 트리거 규칙이 URL과 올바르게 일치하는지 확인
함수 호출 오류
"nfStart is not a function" 오류
증상:
ReferenceError: nfStart is not defined- 호출 시 함수가 정의되지 않음
해결 방법:
- 함수 가용성 확인: 호출하기 전에 항상 함수가 존재하는지 확인
if (typeof window.nfStart === 'function') {
nfStart(keys, callback);
} else {
// 대체 로직
console.log('NetFUNNEL not available');
}
- 스크립트 로드 순서: NetFUNNEL 스크립트가 코드보다 먼저 로드되는지 확인
- 로드 대기:
window.load이벤트 후에 함수 호출
window.addEventListener('load', function() {
// 여기서 NetFUNNEL 함수를 안전하게 호출할 수 있음
});
콜백이 실행되지 않음
증상:
nfStart가 호출되었지만 콜백이 실행되지 않음- 응답을 받지 못함
해결 방법:
- 네트워크 확인: NetFUNNEL 서버에 대한 네트워크 요청 확인
- 콘솔 로그: 디버깅을 위해
data-nf-print-log="true"활성화 - 세그먼트 상태: 세그먼트가 Block 상태가 아닌지 확인
- 진입 허용 수: 진입 허용 수가 진입을 허용하는지 확인
네트워크 및 연결 문제
네트워크 타임아웃 오류
증상:
- 상태 코드 1002와 함께
NetworkError - 요청이 타임아웃됨
해결 방법:
- 타임아웃 증가:
data-nf-network-timeout을 더 높은 값으로 설정 (최대 10000ms) - 재시도 구성:
data-nf-retry-count증가 - 네트워크 복구:
data-nf-use-network-recovery-mode="true"활성화
<script
src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
data-nf-client-id="your-client-id"
data-nf-network-timeout="5000"
data-nf-retry-count="2"
data-nf-use-network-recovery-mode="true"
></script>
네트워크 연결 안 됨 오류
증상:
- 상태 코드 1001과 함께
NetworkError - 인터넷 연결 없음
해결 방법:
- 연결 확인: 인터넷 연결 확인
- 방화벽: NetFUNNEL 도메인이 차단되지 않았는지 확인
- 프록시 설정: 필요한 경우 프록시 구성
- 오류 처리: 적절한 NetworkError 처리 구현
function nfCallback(response) {
if (response.status === 'NetworkError') {
// 사용자 친화적인 메시지 표시
alert('네트워크 연결 문제가 발생했습니다. 인터넷 연결을 확인해 주세요.');
// 선택적으로 재시도하거나 계속 진행
}
}
대기실 문제
대기실이 표시되지 않음
증상:
- 대기실이 나타나지 않음
- 사용자가 직접 진행함
해결 방법:
- 진입 허용 수: 테스트를 위해 0으로 설정
- 세그먼트 활성화: 세그먼트가 활성화되어 있는지 확인
- 트리거 규칙: URL 일치 규칙 확인
- 템플릿 설정:
data-nf-use-netfunnel-template="true"확인
대기실이 멈춤 (끝나지 않음)
증상:
- 대기실이 나타나지만 진입을 허용하지 않음
- 무한 대기
해결 방법:
- 진입 허용 수: 진입 허용 수 값 증가
- 세그먼트 상태: 세그먼트가 Block 상태인지 확인
- 네트워크 문제: 네트워크 연결 확인
- 서버 상태: NetFUNNEL 서버 상태 확인
모달이 나타나지 않음 (코드 기반)
증상:
- 코드 기반 통합에서 모달이 표시되지 않음
- 대신 페이지가 리디렉션됨
해결 방법:
- 통합 방법: URL 트리거가 아닌 코드 기반을 사용하고 있는지 확인
- 함수 호출:
nfStart가 올바르게 호출되는지 확인 - 콜백 처리: 콜백이 구현되어 있는지 확인
- 템플릿 설정:
data-nf-use-netfunnel-template="true"확인
키 관리 문제
키가 반환되지 않음
증상:
- 다음 사용자가 무한정 대기함
- 대기열이 진행되지 않음
해결 방법:
- 항상 nfStop 호출:
nfStop/nfStopSection이 호출되는지 확인 - 오류 처리: 오류 시나리오에서도 키 반환
- 타임아웃 설정: 세그먼트 타임아웃 설정 확인
- 함수 일치: 시작/중지에 동일한 키 사용
// 항상 키 반환
try {
performAction();
nfStop(keys); // 성공 사례
} catch (error) {
nfStop(keys); // 오류 사례 - 여전히 키 반환
}
키 불일치 오류
증상:
- 잘못된 키에 대한 서버 오류
- 키를 찾을 수 없음 오류
해결 방법:
- 키 일관성: 시작/중지 함수에 동일한 키 사용
- 키 범위: 다른 동작 간에 키를 재사용하지 않음
- 타이밍: 시작이 완료되기 전에 중지 호출하지 않음
// 올바름: 시작 및 중지에 동일한 키 사용
const keys = { projectKey: 'service_1', segmentKey: 'segKey_123' };
nfStart(keys, callback);
nfStop(keys);
구성 문제
잘못된 프로젝트/세그먼트 키
증상:
- 함수가 호출되었지만 효과가 없음
- 잘못된 세그먼트 동작
해결 방법:
- 콘솔 확인: NetFUNNEL 콘솔에서 키를 다시 확인
- 정확히 복사: 콘솔에 표시된 대로 키를 정확히 복사
- 환경: 올바른 환경 사용 중인지 확인 (프로덕션 vs 스테이징)
Data 속성이 작동하지 않음
증상:
- 구성 옵션이 적용되지 않음
- 예상치 못한 동작
해결 방법:
- 속성 형식: 올바른 형식 사용 (예:
data-nf-timeout="5000") - 값 범위: 값이 허용된 범위 내에 있는지 확인
- 방법 호환성: 속성이 통합 방법에 적용되는지 확인
브라우저 및 환경 문제
광고 차단기 간섭
증상:
- 스크립트가 차단됨
- 네트워크 요청이 차단됨
해결 방법:
- 도메인 허용 목록: NetFUNNEL 도메인을 광고 차단기 허용 목록에 추가
- 사용자 지침: 사용자에게 지침 제공
- 대체 처리: 우아한 성능 저하 구현
브라우저 호환성
증상:
- 특정 브라우저에서 함수가 작동하지 않음
- JavaScript 오류
해결 방법:
- 브라우저 지원: 브라우저 호환성 확인
- 폴리필: 오래된 브라우저에 필요한 폴리필 추가
- 기능 감지: 함수 호출 전 기능 감지 사용
개발 vs 프로덕션
증상:
- 개발 환경에서는 작동하지만 프로덕션에서는 작동하지 않음
- 환경 간 다른 동작
해결 방법:
- 환경 URL: 각 환경에 대한 올바른 URL 사용
- 콘솔 구성: 개발/프로덕션용 별도 세그먼트 설정
- 캐싱: 브라우저 캐시 및 CDN 캐시 지우기
FAQ
스크립트를 공통 JS 파일에 넣을 수 있나요?
A: 예, 스크립트를 동적으로 삽입할 수 있습니다:
<script src="./netfunnel.js" defer></script>
// netfunnel.js
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";
document.head.appendChild(scriptNF);
NetworkError를 어떻게 처리해야 하나요?
A: 사용자에게 알리고 nfStart를 재시도하거나 원래 로직을 계속 진행하세요:
function handleNetworkError(response) {
if (confirm('네트워크 오류가 발생했습니다. 다시 시도하시겠습니까?')) {
nfStart(keys, callback); // 재시도
} else {
performOriginalLogic(); // 어쨌든 계속 진행
}
}
키를 반환하는 것을 잊어버리면 어떻게 되나요?
A: 키는 서버 타임아웃에 의해 자동으로 반환될 수 있지만, 이로 인해 병목 현상이 발생할 수 있습니다. 항상 명시적으로 반환하세요:
// 좋음: 항상 키 반환
nfStart(keys, function(response) {
if (response.status === 'Success') {
performAction()
.then(() => nfStop(keys))
.catch(() => nfStop(keys)); // 오류 발생 시에도
}
});
URL 트리거와 코드 기반 방법을 모두 사용할 수 있나요?
A: 예, 단일 서비스 내에서 방법을 혼합할 수 있습니다:
- URL 트리거를 페이지 진입 속도 제어에 사용
- 코드 기반을 비즈니스 동시 사용자 수 제어에 사용
그러나 운영 복잡성을 줄이기 위해 하나의 방법을 우선적으로 사용하는 것이 권장됩니다.
NetFUNNEL 통합을 어떻게 디버깅하나요?
A: 로깅을 활성화하고 콘솔을 확인하세요:
<script
src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
data-nf-client-id="your-client-id"
data-nf-print-log="true"
></script>
그런 다음 DevTools 콘솔에서 NetFUNNEL 로그 메시지를 확인하세요.
기본 제어와 구간 제어의 차이점은 무엇인가요?
A:
- 기본 제어: 진입 속도를 제한합니다 (사용자가 얼마나 빨리 진입할 수 있는지)
- 구간 제어: 고정된 동시 사용자 수를 유지합니다 (동시에 활성화될 수 있는 사용자 수)
간단한 진입 제한에는 기본 제어를 사용하고, 특정 동시성 수준을 유지하려면 구간 제어를 사용하세요.
도움 받기
여전히 문제가 발생하는 경우:
- 콘솔 로그 확인:
data-nf-print-log="true"를 활성화하고 브라우저 콘솔 확인 - 구성 확인: NetFUNNEL 콘솔의 모든 설정을 다시 확인
- 간단한 설정으로 테스트: 기본 구성으로 시작하고 점진적으로 복잡성 추가
- 지원팀에 문의: 구체적인 오류 세부 정보와 함께 NetFUNNEL 지원팀에 문의