브라우저 에이전트 적용

와탭 브라우저 모니터링 서비스를 사용하기 위해서는 회원 가입 후 프로젝트를 생성하고 웹 애플리케이션에 와탭 브라우저 에이전트를 적용해야 합니다.

다음 동영상 가이드를 참조하세요.

와탭 브라우저 에이전트 설치

에이전트 설치 화면의 안내에 따라 웹 애플리케이션에 적용할 와탭 브라우저 에이전트 코드를 적용하세요.

와탭 브라우저 에이전트 설치

데이터 수집 샘플링

와탭 브라우저 에이전트는 사용자 세션을 기준으로 데이터를 수집합니다. 수집하는 전체 세션의 비율을 0부터 100까지 설정할 수 있습니다.

와탭 브라우저 에이전트 스크립트

와탭 브라우저 에이전트는 인라인 스크립트 형태로 제공합니다. 설치 안내에서 제공하는 스크립트 코드를 모니터링하려는 모든 HTML 페이지의 <head> 태그 내부 최상단에 추가하세요.

다음 두가지 방식 중 원하는 방식을 선택해 에이전트를 적용하세요.

Async(비동기 로드): 웹 애플리케이션에 와탭 브라우저 에이전트를 비동기 형태로 로드합니다.
- 웹 애플리케이션의 로드 성능에 영향을 미치지 않습니다.
- 브라우저 에이전트가 로드되기 전 발생한 AJAX, 에러 등의 데이터가 누락될 수 있습니다.
Sync(동기 로드): 웹 애플리케이션에 와탭 브라우저 에이전트를 동기 형태로 로드합니다.
- 웹 애플리케이션 로드 시 모든 데이터를 수집하려면 권장합니다.
- 웹 애플리케이션 로드에 영향을 미칠 수 있습니다.

설치 안내에서 제공하는 스크립트는 즉시 실행 함수의 인자로 에이전트 번들 경로와 설정 전역 객체 이름을 함께 넘깁니다. 두 값은 자리가 정해져 있습니다.

Position	Value	Description
4번째 인자	에이전트 번들 경로	에이전트 파일을 직접 호스팅한다면 이 자리를 변경
5번째 인자	`'WhatapBrowserAgent'`	설정을 담는 전역 객체 이름. 변경 금지

5번째 인자를 번들 경로로 바꾸면 에이전트가 설정 객체를 찾지 못해 초기화가 일어나지 않습니다. 이때 브라우저 콘솔에는 아무 메시지도 출력되지 않습니다. 데이터가 들어오지 않는데 오류도 보이지 않는다면 이 자리를 먼저 확인하세요.

와탭 브라우저 에이전트 옵션 설정

와탭 브라우저 에이전트에 적용할 옵션을 설정합니다. 옵션은 설치 스크립트의 Config 객체에서 설정할 수 있습니다. 프로젝트 액세스 키, 전체 사용자 세션 비율, 수집 제외 리소스 도메인 등을 설정할 수 있습니다.

config example
config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  ignoreOrigins: [ 'https://ignore-site.com/', /^(https?://)([^/]*)(ignore-site.io)(/)(.*)/i ],
}

옵션 파라미터

projectAccessKey String required

프로젝트 액세스 키입니다. 프로젝트 설치 안내(관리 > 에이전트 설치)에서 확인할 수 있습니다.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
}

pcode Number required

프로젝트 액세스 키입니다. 프로젝트 설치 안내(관리 > 에이전트 설치)에서 확인할 수 있습니다.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
}

sampleRate Number required

수집하는 사용자 세션 비율을 설정할 수 있습니다. 0부터 100까지 설정할 수 있습니다.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
}

브라우저 에이전트의 sampleRate는 0~100 스케일입니다. 와탭 모바일 에이전트의 샘플링 설정(setSampling)은 0.0~1.0 스케일이라 기준이 서로 다릅니다. 모바일 쪽 값인 1.0을 sampleRate에 그대로 입력하면 경고 없이 전체 세션의 1%만 수집합니다. 두 에이전트를 함께 적용하는 WebView 환경에서 특히 헷갈리기 쉬운 부분입니다.

proxyBaseUrl String required

에이전트가 수집한 데이터를 전송하는 URL입니다. 프로젝트의 리전에 따라 값이 다르므로, 와탭 모니터링 서비스의 관리 > 에이전트 설치 화면에서 제공하는 스크립트의 값을 그대로 사용하세요.

에이전트 스크립트 파일 주소(<script src>)와는 다른 값입니다. 이 값을 잘못 설정하면 수집 데이터가 전송되지 않습니다.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
}

proxyBaseUrl은 모바일 앱 WebView 연동(isWebView: true)에서도 반드시 설정해야 합니다. 연동 상태에서는 실제 전송을 모바일 에이전트가 맡으므로 이 주소로 요청이 나가지는 않지만, 브라우저 에이전트는 이 값이 있어야 수집을 시작합니다. 값을 설정하지 않으면 브라우저 콘솔에 다음 경고가 출력된 뒤 데이터가 전혀 전송되지 않습니다.

[WhatapRUM] Config warning: proxyBaseUrl is not set -- RUM data transmission and health check are disabled.

브릿지에 도달하지 못한 구간의 폴백 전송도 이 주소로 나갑니다. 연동 적용에서도 유효한 값을 넣어야 데이터 유실을 막을 수 있습니다.

ignorePageUrls Array<string | RegExp> optional

수집에서 제외할 페이지 URL 목록입니다. 문자열 매칭은 startsWith 방식으로 이루어집니다.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  ignorePageUrls: ["https://test.webpage.com/", "http://localhost:2003/page1/", /^.localhost.$/i]
}

ignoreResources Array<string | RegExp> optional

수집에서 제외할 리소스 URL 목록입니다. 문자열 매칭은 startsWith 방식으로 이루어집니다.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  ignoreResources: ["https://test.web.com/yard/api/flush", "http://localhost:2003/whatap-browser-agent.js",  /^.\/path1\/api.$/i]
}

ignoreErrors Array<string | RegExp> optional

수집에서 제외할 브라우저 에러 목록입니다. 문자열 매칭은 includes 방식으로 이루어집니다.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  ignoreErrors: ["cannot read", "cors", "basic"]
}

collectUserClick Boolean optional

기본값 false

사용자 클릭 이벤트를 수집할 수 있습니다. 수집한 데이터를 확인하는 방법은 다음 문서를 참조하세요.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  collectUserClick: true
}

sessionReplaySampleRate Number optional

기본값 0

세션 리플레이 데이터를 수집할 세션 비율입니다. 수집 대상 사용자 세션 중 0부터 100까지 설정할 수 있습니다.

예를 들어, sampleRate를 50으로 설정하고 sessionReplaySampleRate를 20으로 설정하면, 전체 세션의 50%가 수집 대상이 되며, 그 중 20%의 세션에서만 세션 리플레이 데이터를 수집합니다.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  sessionReplaySampleRate: 50
}

sessionReplayMaskAllTexts Boolean optional

기본값 true

값을 false로 설정하면 마스킹 처리 없이 모든 텍스트 데이터를 수집합니다.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  sessionReplaySampleRate: 50, 
  sessionReplayMaskAllTexts: false
}

sessionReplayMaskAllInputs Boolean optional

기본값 true

값을 false로 설정하면 마스킹 처리 없이 모든 입력(Input) 필드 영역의 데이터를 수집합니다.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  sessionReplaySampleRate: 50, 
  sessionReplayMaskAllInputs: false
}

sessionReplayCollectAllBrowser Boolean optional

기본값 false

requestIdleCallback()을 지원하지 않는 브라우저에서도 세션 리플레이 데이터를 수집합니다. 예, Safari, Safari on iOS

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  sessionReplaySampleRate: 50, 
  sessionReplayCollectAllBrowser: true
}

ignoreStatusZero Boolean optional

기본값 false

AJAX 요청의 상태 코드가 0인 경우 해당 데이터를 수집에서 제외하는 옵션입니다.

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}",
  ignoreStatusZero: true
}

노트

세션 리플레이에 대한 자세한 내용은 다음 문서를 참조하세요.
세션 리플레이 수집을 지원하는 브라우저에 대한 자세한 내용은 다음 문서를 참조하세요.

그 밖의 초기화 옵션

앞의 옵션 파라미터 외에 실행 환경에 따라 판단이 필요한 옵션이 있습니다. 브라우저 에이전트 소스 저장소의 정본 문서(README.md, docs/webview-integration.md)에서 확인한 기본값과 동작은 다음과 같습니다.

Option	Type	Default	Description
`isWebView`	`boolean`	`false`	데이터 전송을 와탭 모바일 에이전트에 위임하는 전송 경로 스위치
`webViewHttpFallback`	`boolean`	`true`	브릿지에 도달하지 못할 때 표준 HTTP 전송으로 폴백. 브라우저 에이전트 3.2.0부터 지원
`allowIframe`	`boolean`	`false`	iframe 안에서의 실행 허용. `false`이면 iframe 내부에서 초기화가 차단됨
`enableHealthCheck`	`boolean`	`false`	초기화 시 프로젝트 헬스 체크 수행. 실패하면 에이전트 정지
`collectAgentError`	`boolean`	`false`	에이전트 내부 오류 수집
`hashRouting`	`boolean`	`false`	`#/경로` 형태의 해시 라우팅 화면 전환을 라우트 변경으로 수집
`ignoreLocalhost`	`boolean`	`false`	localhost 대상 요청을 수집에서 제외
`cookieSecure`	`boolean`	`false`	에이전트 쿠키에 `secure` 플래그 지정

초기화 시에만 설정할 수 있는 옵션

다음 옵션은 초기화 시점에 한 번만 판정합니다. 값을 변경하려면 페이지의 설치 스크립트를 수정한 다음 페이지를 다시 불러와야 합니다.

isWebView, webViewHttpFallback, allowIframe, enableHealthCheck, collectAgentError, hashRouting, pageLoadEndPoint, maxPageLoadTime, cookieSecure

에이전트 자체 통신은 수집하지 않습니다

주소에 /rum/ 또는 /whatap/가 포함된 요청은 에이전트가 자기 자신의 통신으로 간주해 수집 대상에서 제외합니다. 서비스 API 경로에 이 문자열이 들어 있다면 해당 요청은 리소스 데이터와 AJAX 데이터에 나타나지 않습니다.

모바일 앱 WebView에서 사용할 때

모바일 앱의 WebView 화면을 와탭 모바일 에이전트와 함께 수집할 때는 브라우저 에이전트 쪽에도 별도 설정이 필요합니다. 앱에서 진행하는 설치와 WebView 등록 절차는 Android 에이전트 적용 문서와 iOS 에이전트 적용 문서를 참조하세요. 이 절은 웹 페이지에 적용하는 브라우저 에이전트 설정만 다룹니다.

연동에는 v2 번들이 필요합니다

WebView 연동은 브라우저 에이전트 3.2.0 이상에서 동작합니다. 연동용 브릿지가 v1 번들에는 들어 있지 않으므로 스크립트 주소를 v2 경로로 지정하세요.

<script src="https://repo.whatap-browser-agent.io/rum/prod/v2/whatap-browser-agent.js"></script>

적용한 파일의 버전은 WhatapRUM.VERSION 값으로 확인할 수 있습니다.

isWebView는 대소문자를 구분합니다

연동을 켜는 옵션 이름은 isWebView이며 W가 대문자입니다. isWebview처럼 소문자 v로 적으면 알 수 없는 키로 처리되어 경고 없이 무시됩니다. 이 경우 데이터는 수집되지만 연동은 이루어지지 않고, 대시보드에서 일반 브라우저로 분류됩니다. 설치 안내 화면에서 복사한 스니펫이 isWebview로 채워지는 사례가 보고되었으므로, 붙여 넣은 다음 표기를 확인하세요.

WebView 환경 권장 설정

Option	Default	Recommended	Description
`proxyBaseUrl`	-	필수 설정	미설정 시 연동 적용에서도 데이터 전송이 중지됨
`sampleRate`	-	적용 확인 중에는 `100`	0~100 스케일. 모바일 에이전트와 기준이 다름
`isWebView`	`false`	`true`	전송을 모바일 에이전트에 위임
`webViewHttpFallback`	`true`	기본값 유지	웹뷰에서 수집 서버에 접근할 수 없는 폐쇄망이라면 `false`
`enableHealthCheck`	`false`	`false` 유지	실패 시 재시도 없이 에이전트 전체가 중지됨
`collectAgentError`	`false`	`false` 유지	모바일 에이전트 브릿지를 거치지 않고 수집 서버로 직접 통신
`sessionReplayCollectAllBrowser`	`false`	리플레이 사용 시 `true`	웹뷰 엔진 종류와 무관하게 녹화
`sessionReplaySampleRate`	`0`	리플레이 사용 시 값 지정	기본값 `0`은 수집하지 않음
`allowIframe`	`false`	iframe 안에서 로드할 때 `true`	미설정 시 iframe 내부에서 초기화가 차단됨
`ignoreLocalhost`	`false`	`false` 유지	Capacitor, Ionic 환경에서 수집 누락의 원인
`hashRouting`	`false`	해시 라우팅 사용 시 `true`	`#/경로` 화면 전환 수집
`cookieSecure`	`false`	화면 주소가 `https://`일 때만 `true`	`capacitor://`, `ionic://` 등에서는 쿠키가 무효화될 수 있음

노트

enableHealthCheck로 수행하는 헬스 체크는 수집 서버와 직접 통신합니다. 응답이 없거나 실패하면 재시도 없이 브라우저 에이전트가 중지되므로 WebView 환경에서는 기본값 false를 그대로 두세요. 같은 경로로 전달되는 원격 설정도 연동 적용에서는 사용할 수 없습니다. 필요한 옵션은 모두 설치 스크립트에 직접 지정하세요.

다음 단계

사용자 정의 이벤트 수집하기

브라우저 모니터링을 통해 웹 서비스의 문제점을 파악하고 사용자 경험을 개선하기 위해, 웹 페이지에서 발생하는 이벤트 중 개발자와 운영자가 원하는 이벤트를 추가로 수집할 수 있는 인터페이스를 제공합니다. 사용자 정의 이벤트를 수집하는 방법에 대한 자세한 내용은 다음 문서를 참조하세요.
실제 사용자 ID 설정하기

브라우저 모니터링에서 실제 사용자의 로그인 ID나 이메일 등으로 사용자 ID를 설정해 데이터를 수집할 수 있습니다. 실제 로그인 ID를 기반으로 사용자 세션 성능과 이벤트 정보를 확인하고, 브라우저 에러 정보를 확인해 문제를 파악할 수 있습니다. 자세한 내용은 다음 문서를 참조하세요.
세션 리플레이 설정하기

세션 리플레이는 사용자가 웹 사이트에서 수행하는 모든 이벤트를 기록하고 재생할 수 있는 기능입니다. 이 기능을 통해 클릭, 스크롤, 입력, 페이지 전환 등의 사용자 행동을 재현할 수 있습니다. 이를 통해 사용자가 실제로 웹사이트와 어떻게 상호 작용하는지 정확히 파악할 수 있습니다. 자세한 내용은 다음 문서를 참조하세요.
모니터링 시작하기

와탭 모니터링 서비스 페이지로 이동해 브라우저 모니터링을 시작하세요. 앞서 생성한 프로젝트를 선택한 다음 대시보드 > 브라우저 모니터링 대시보드 메뉴로 이동하세요. 모니터링 현황을 파악할 수 있습니다. 브라우저 모니터링 대시보드 메뉴에 대한 자세한 내용은 다음 문서를 참조하세요.

와탭 브라우저 에이전트 설치​

데이터 수집 샘플링​

와탭 브라우저 에이전트 스크립트​

와탭 브라우저 에이전트 옵션 설정​

옵션 파라미터​

그 밖의 초기화 옵션​

초기화 시에만 설정할 수 있는 옵션​

에이전트 자체 통신은 수집하지 않습니다​

모바일 앱 WebView에서 사용할 때​

연동에는 v2 번들이 필요합니다​

isWebView는 대소문자를 구분합니다​

WebView 환경 권장 설정​

다음 단계​

와탭 브라우저 에이전트 설치

데이터 수집 샘플링

와탭 브라우저 에이전트 스크립트

와탭 브라우저 에이전트 옵션 설정

옵션 파라미터

그 밖의 초기화 옵션

초기화 시에만 설정할 수 있는 옵션

에이전트 자체 통신은 수집하지 않습니다

모바일 앱 WebView에서 사용할 때

연동에는 v2 번들이 필요합니다

isWebView는 대소문자를 구분합니다

WebView 환경 권장 설정

다음 단계