Browser Agent 통합 가이드

Browser Agent를 실제 서비스에 통합하기 위한 단계별 가이드입니다.

1. 에이전트 소개

EUM(End-User Monitoring) 에이전트는 사용자 경험을 모니터링하고 분석하기 위한 JavaScript 기반 도구입니다. 이 에이전트를 통해 사용자는 End-User의 다양한 활동을 추적하고, 성능 데이터를 수집할 수 있습니다. 특히 End-User의 트래픽이 집중되는 지점을 식별하여 사용자가 NetFUNNEL의 가상 대기실을 효과적으로 적용할 수 있도록 지원함으로써, 트래픽 과부하를 방지하고 안정적인 서비스 제공할 수 있습니다.

1.1 최소 요구 사항

브라우저: Chrome 80+, Firefox 78+, Safari 13+, Edge 80+ 이상
JavaScript: ES6 (ECMAScript 2015) 지원
네트워크: HTTPS 연결 권장

1.2 지원 환경

SPA (Single Page Application): React, Vue.js, Angular 등
MPA (Multi Page Application): 전통적인 멀티 페이지 웹사이트
모바일 웹: 모바일 브라우저 환경

2. 에이전트 설치

info

본 가이드는 모든 주요 웹 브라우저 환경을 기준으로 작성되었습니다.

2.1 에이전트 다운로드

에이전트 파일을 다운로드 합니다.

Download

2.2 스크립트 설치

Browser EUM 에이전트는 두 가지 방법으로 설치할 수 있습니다.

HTML 파일에 직접 삽입

HTML 파일의 <head> 태그 내에 아래 코드를 복사하여 붙여넣습니다. 이 방법은 간단하고 빠르게 적용할 수 있는 장점이 있습니다.

HTML Injection

<script src="https://agent-lib.stclab.com/agents/eum/browser/eum-browser.js" defer onload="initializeEUM()"></script>
<script>
    async function initializeEUM() {
        const initResult = await window.STC_EUM.initialize({
            serverURL: "undefined",
            settingURL: "undefined",
            clientId: "{TENANT_ID}",
            trackResource: true,
            printLog: false,
        });
    }
</script>

공통 JavaScript 파일에 삽입

각 HTML 파일에 스크립트를 삽입하는 대신, 공통으로 사용되는 JavaScript 파일에 다음 코드를 추가하는 것이 관리 및 유지보수 측면에서 더 효율적입니다.

JavaScript Injection

var scriptEUM = document.createElement('script');
scriptEUM.src = 'https://agent-lib.stclab.com/agents/eum/browser/eum-browser.js';
scriptEUM.onload = async function () {
    const initResult = await window.STC_EUM.initialize({
        serverURL: 'undefined',
        settingURL: 'undefined',
        clientId: '{TENANT_ID}',
        trackResource: true,
        printLog: false,
    });
};
document.head.appendChild(scriptEUM);

파라미터	타입	설명	필수	기본값
serverURL	String	EUM 서버 주소	O	-
settingURL	String	EUM 설정 파일 URL	O	-
clientId	String	EUM 클라이언트 ID	O	-
trackResource	Boolean	리소스 이벤트 추적 활성화 여부	X	true
printLog	Boolean	디버그 로그 출력 여부	X	false

2.3 초기화 확인

초기화 성공

[EUM] Initialization Success
[EUM] {"isSuccess":true,"version":"1.0.0"}

초기화 실패

[EUM] Initialization failed
[EUM] {"isSuccess":false,"version":"1.0.0"}

FAQ

Q: 초기화 실패 시 어떻게 해야 하나요?

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

서버 URL과 설정 URL이 올바른지 확인
네트워크 연결 상태 확인
클라이언트 ID가 유효한지 확인
브라우저 콘솔에서 구체적인 오류 메시지 확인
CORS 설정이 올바른지 확인

Q: SPA(Single Page Application)에서 페이지 전환이 추적되나요?

A: 네, Browser EUM 에이전트는 SPA의 라우터 변경을 자동으로 감지하고 페이지 전환 이벤트를 추적합니다.

Q: 특정 이벤트만 수집하고 싶어요

A: trackResource 파라미터를 false로 설정하면 리소스 이벤트 수집을 비활성화할 수 있습니다. 세션과 화면 이벤트는 항상 수집됩니다.

Q: 프로덕션 환경에서 로그를 끄려면?

A: 초기화 시 printLog: false로 설정하거나 환경 변수를 사용하여 개발 환경에서만 로그가 출력되도록 설정하세요.

Q: 모바일 웹에서 성능에 영향을 주나요?

A: Browser EUM 에이전트는 가벼운 설계로 성능에 미치는 영향을 최소화했습니다. 필요시 trackResource: false 설정으로 리소스 추적을 비활성화하여 성능을 더욱 최적화할 수 있습니다.