Web/JavaScript 에이전트
개요
NetFUNNEL JavaScript 에이전트는 웹 브라우저에서 NetFUNNEL 서버와 통신하는 NetFUNNEL 전용 클라이언트입니다.
에이전트 설치
초기화
NetFUNNEL JavaScript 에이전트는 페이지 로드 시 초기화 코드를 통해서 서비스에 적용됩니다. 따라서 서비스 로직보다 먼저 실행되야 하기 때문에 head 태그의 상위에 위치하는 것이 좋습니다.
코드
NetFUNNEL JavaScript 에이전트를 사용할 페이지의 HTML에 초기화 코드를 추가해주세요.
<html>
<head>
...
<script
src="{{AGENT_URL}}"
data-nf-client-id="{{CLIENT_ID}}"
></script>
...
</head>
</html>
에이전트 적용
NetFUNNEL JavaScript 에이전트로 대기열 제어 지점을 설정하는 방식에는 URL 트리거 적용 과 코드 기반 적용 두 가지가 있습니다.
URL 트리거 적용
넷퍼넬 콘솔의 세그먼트 설정에서 트리거 규칙을 통해 적용합니다. 사용자가 접속한 페이지의 URL이 트리거 규칙과 매칭되면 대기열을 적용합니다. 넷퍼넬 콘솔에서 설정하기 때문에 애플리케이션 재배포가 필요없고 대기열 적용 지점을 실시간으로 변경 가능합니다.
코드 기반 적용
서비스 중인 애플리케이션 코드에서 넷퍼넬에서 제공하는 함수를 호출합니다. 대기열 적용 지점을 변경할 때마다 재배포가 필요하지만, 트래픽이 발생하기 전에 대기실을 노출하기 때문에 트래픽을 사전에 효과적으로 제어할 수 있습니다.
NetFUNNEL JavaScript 에이전트를 설치한 고객은 두 가지 적용 방식을 사용할 수 있지만, 설정의 간소화와 관리의 용이성을 위해 한 가지만 사용하시기 바랍니다.
URL 트리거 적용
대기열 제어 지점은 NetFUNNEL 콘솔의 세그먼트 트리거 규칙을 통해 설정할 수 있습니다. 사용자가 접속한 페이지의 URL과 트리거 규칙을 비교하여 일치하는 경우 대기열이 적용됩니다.
동작 흐름
대기 전: 페이지 로드 → 에이전트 초기화 → 트리거 규칙 매치 대기 중: 넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 페이지로 이동 대기 후: 서비스 페이지 진입 → 넷퍼넬 키 반납
설정 옵션
- Logical Operator: 두 개 이상의 트리거 규칙을 생성할 때, 서로의 관계를 and 또는 or 연산자로 결정합니다.
- Validator: 트리거 규칙이 적용될 대상의 최상위 범위를 정의합니다. 현재는 URL만 제공하고 있습니다.
- Component: Validator에 의해 정의된 범위 내에서 더 세부적으로 규칙을 적용할 대상을 지정합니다. 이는 URL 전체 또는 경로(Path) 등이 될 수 있으며, 특정 페이지나 자원에 규칙을 적용하는 데 사용됩니다.
- Negate: 설정한 조건의 반대 경우를 적용하고 싶을 때 사용합니다. 예를 들어, 특정 조건이 '참'이 아닐 때 규칙을 적용하고자 할 때 이 옵션을 활성화합니다.
- Match: 규칙이 적용될 조건의 유형을 정의합니다. 'Equals', 'Exists' 등의 옵션을 통해 특정 값과 일치하는 경우, 또는 특정 조건이 존재하는 경우 등을 기준으로 규칙을 적용할 수 있습니다.
- Value: 규칙 적용 시 비교 대상이 되는 구체적인 값을 지정합니다. 이 값은 'Match' 조건과 함께 사용되어, 규칙이 어떤 경우에 활성화될지를 결정합니다.
- Aa: Value에 대해 비교할 때 대소문자를 구분할지 결정합니다.
Match 옵션
- Exists: URL에 해당 Component가 존재하는지 확인합니다. (Component가 Path일 때만 사용 가능합니다.)
- Equals: Component의 값과 Value가 완전히 일치하는지를 확인합니다.
- Contains: Component의 값에 지정된 Value가 포함되어 있는지를 확인합니다.
- StartsWith: Component의 값이 지정된 Value로 시작하는지를 확인합니다.
- EndsWith: Component의 값이 지정된 Value로 끝나는지를 확인합니다.
트리거 규칙 테스트
대기열을 적용하고자하는 URL이 트리거 규칙에 부합하는지 미리 확인하기 위하여 사전에 테스트할 수 있습니다.
코드 기반 적용
코드 기반 적용에는 시작 함수와 종료 함수가 있습니다. 시작 함수를 호출하여 넷퍼넬 서버에서 키를 발급하고, 대기를 완료하여 진입하면 종료 함수를 호출하여 키를 반납합니다. 키를 반납함으로써 다음 대기자가 진입할 수 있게 됩니다.
동작 흐름
- 대기 전: 페이지 로드 → 에이전트 초기화 → 시작 함수 실행
- 대기 중: 넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 노출
- 대기 후: Success 로직 실행 → 종료 함수 실행
기본 제어
시작 함수
- 함수명:
nfStart - 설명: 대기를 적용하고 싶은 지점에서 함수를 호출하여 키를 발급하고 대기실을 노출시킵니다.
- 적용 위치: 페이지 진입이나 이벤트 시작 부분에 적용합니다.
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 기본제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 기본제어 세그먼트 키 | O |
| callback | Function | 대기실 이벤트 처리를 위한 사용자 정의 콜백 함수 | O |
nfStart({
projectKey: "{{PROJECT_KEY}}",
segmentKey: "{{SEGMENT_KEY}}"
}, function(response) {
// TODO: response에 따라 상황에 맞는 콜백 함수를 구현합니다.
nfCallback(response);
});
종료 함수
- 함수명:
nfStop - 설명: 진입을 완료한 후 키 반납을 위해 사용합니다.
- 적용 위치: 시작 함수 종료 후 또는 진입 한 유저의 활동이 완료되는 지점에 적용합니다.
종료 함수를 실행하지 않으면 세그먼트의 타임아웃 설정에 따라 자동으로 반납 처리합니다.
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 기본제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 기본제어 세그먼트 키 | O |
nfStop({
projectKey: "{{PROJECT_KEY}}",
segmentKey: "{{SEGMENT_KEY}}"
});
구간 제어
구간제어란, 애플리케이션의 특정 구간에서 동시 접속자 수를 일정한 값으로 유지하도록 제어하는 기능입니다. 시작 함수 호출 시 키를 발급하고, 종료 함수를 호출하기 전까지는 유저가 활동 구간에 있는 것으로 판단하여 다음 대기자를 진입시키지 않습니다. 종료 함수를 호출하면 키를 반납하고 다음 대기자가 진입하게 됩니다.
시작 함수
- 함수명:
nfStartSection - 설명: 대기를 적용하고 싶은 지점에서 함수를 호출하여 키를 발급하고 대기실을 노출시킵니다.
- 적용 위치: 페이지 진입이나 이벤트 시작 부분에 적용합니다.
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 구간제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 구간제어 세그먼트 키 | O |
| callback | Function | 대기실 이벤트 처리를 위한 사용자 정의 콜백 함수 | O |
nfStartSection({
projectKey: "{{PROJECT_KEY}}",
segmentKey: "{{SEGMENT_KEY}}"
}, function(response) {
// TODO: response에 따라 상황에 맞는 콜백 함수를 구현합니다.
nfCallback(response);
});
종료 함수
- 함수명:
nfStopSection - 설명: 진입을 완료한 후 키 반납을 위해 사용합니다.
- 적용 위치: 진입한 유저의 활동 구간이 종료되는 지점에 적용합니다.
종료 함수를 실행하지 않으면 유저가 활동 구간에 계속 남아있는 것으로 간주되어 다음 대기자의 진입이 늦춰질 수 있습니다.
| 파라미터 | 타입 | 설명 | 필수 여부 |
|---|---|---|---|
| projectKey | String | NetFUNNEL 콘솔의 구간제어 프로젝트 키 | O |
| segmentKey | String | NetFUNNEL 콘솔의 구간제어 세그먼트 키 | O |
nfStopSection({
projectKey: "{{PROJECT_KEY}}",
segmentKey: "{{SEGMENT_KEY}}"
});
콜백 함수
기본제어와 구간제어 시작 함수의 두번째 파라미터인 콜백 함수에서 넷퍼넬 서버로부터의 응답을 받을 수 있습니다. 응답 결과에 따라 사용자는 다양한 처리 로직을 수행할 수 있습니다.
상태값 ‘Success’, ‘Error’, ‘NetworkError’에 대해서는 필수적으로 처리를 해야 합니다. 그 외의 상태값은 처리하지 않아도 서비스에 영향이 없습니다.
Success
| statusCode | message | 설명 |
|---|---|---|
| 200 | Success | 대기열을 정상적으로 통과하여 서비스에 진입 |
| 300 | Bypass | 구독/라이선스 만료 프로젝트/세그먼트 비활성화 data-nf-error-bypass=true로 설정 |
| 303 | Express | 진입 성공 시 동작 |
Error
| statusCode | message | 설명 |
|---|---|---|
| 500 | Server Error | 존재하지 않는 프로젝트/세그먼트 키 사용 대기 중 세그먼트 삭제 서버 에러로 인한 응답 누락 |
NetwrokError
| statusCode | message | 설명 |
|---|---|---|
| 1001 | Network Not Connected | 네트워크 연결 차단 |
| 1002 | Network Timeout | 네트워크 지연 유효하지 않은 대기실 html 주소 넷퍼넬 서버 다운 |
Block
| statusCode | message | 설명 |
|---|---|---|
| 301 | Block | 세그먼트 차단 |
IpBlock
| statusCode | message | 설명 |
|---|---|---|
| 302 | Macro Block | 블랙리스트 BotManager Basic 활성화 |
Close
| statusCode | message | 설명 |
|---|---|---|
| 499 | Canceled Waiting Room | 기본 대기실의 취소 버튼 클릭 |
| 498 | Closed Blocking Room | 차단실의 닫기 버튼 클릭 |
| 497 | Closed Macro Blocking Room | 매크로 차단실의 닫기 버튼 클릭 |
| 496 | Closed PreWaiting Room | 사전 대기실의 닫기 버튼 클릭 |
| 495 | Closed PostWaiting Room | 사후 대기실의 닫기 버튼 클릭 |
function nfCallback(response) {
const { status, statusCode, message } = response;
switch(status) {
case 'Success':
// 진입 또는 우회 응답을 받은 경우로, 넷퍼넬을 적용하기 전의 기존 서비스 로직을 실행합니다.
// ex - 페이지 이동, 함수 실행, API 요청
break;
case 'Error':
// 시스템 에러가 발생한 경우로, 원활한 서비스 이용을 위해 Succss와 동일하게 기존 서비스 로직을 실행합니다.
// ex - 페이지 이동, 함수 실행, API 요청
break;
case 'NetworkError':
// 네트워크 에러가 발생한 경우로, 기존 서비스 로직을 실행하거나 알림 후 다시 대기열에 진입하도록 합니다.
// ex - 페이지 이동, 함수 실행, API 요청, alert("네트워크 요청을 실패하여 재시도합니다.");
break;
case 'Block':
// 진입 상태가 차단인 경우로, 차단을 알리거나 아무 처리하지 않아도 됩니다.
// ex - alert("진입이 차단된 페이지입니다.");
break;
case 'IpBlock':
// 반복 요청으로 인해 차단된 경우로, 차단을 알리거나 아무 처리하지 않아도 됩니다.
// ex - alert("반복된 요청으로 차단되었습니다.");
break;
case 'Close':
// 대기실의 닫기 또는 취소버튼을 클릭한 경우로, 대기 취소를 알리거나 아무 처리하지 않아도 됩니다.
// ex - alert("대기를 취소하였습니다.");
break;
default:
console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
}
}
부가 기능
NetFUNNEL JavaScript 에이전트에서는 다양한 부가 기능을 제공합니다. 부가 기능을 활성화하려면 초기화 코드에 설정값을 추가해야 합니다. 적용 방식에 따라 사용할 수 있는 부가 기능이 다르니 아래 표를 참고해주세요.
- UTI: URL 트리거 적용(URL Triggered Integration)
- CBI: 코드 기반 적용(Code Based Integration)
초기화 코드 설정값
| data 속성명 | 적용 방식 | 설명 | 기본값 |
|---|---|---|---|
| data-nf-network-timeout | UTI, CBI | 네트워크 응답 최대 대기 시간 | 3000 |
| data-nf-retry-count | UTI, CBI | 네트워크 재시도 횟수 | 0 |
| data-nf-custom-cookie-domain | UTI, CBI | 쿠키 저장 시 도메인 설정 | 빈 값 |
| data-nf-use-network-recovery-mode | UTI, CBI | 네트워크 에러 시 대기실 유지 및 회복 | false |
| data-nf-storage-type | UTI, CBI | 브라우저 저장소 선택 | both |
| data-nf-return-key | UTI | 키 반납 처리 | true |
| data-nf-error-bypass | CBI | Error, NetworkError 대신 Success 상태값 반환 | false |
| data-nf-use-netfunnel-template | CBI | 자체 커스텀 대기실 사용 | true |
| data-nf-health-check-url | CBI | 네트워크 헬스 체크 주소 | 빈 값 |