Web (WPM)

1. [공통] WebAgent 설치

이 문서는 Browser 환경에서의 IMQA Web Agent를 적용하는 방법을 제공합니다.

IMQA WebAgent는 2가지 방식으로 설치 방법을 제공하고 있습니다. CDN 서버로 연결하거나, 설치형 혹은 CDN으로 요청을 못하시는 경우 해당 스크립트를 다운로드 받아서 사용 가능합니다. 아래의 링크를 통해서 마우스 오른쪽 버튼을 누른 후 “다른 이름으로 저장”을 눌러서 연결해 주세요.

WebAgent : https://cdn.imqa.io/agent/web-agent.js WebviewAgent : https://cdn.imqa.io/agent/webview-agent.js

1.1. WPM 단독 사용 (WebAgent 설치)

WPM 서비스만을 이용하며, 웹 브라우저 애플리케이션 구성에서의 웹 성능 분석을 위한 Agent 설치 방법입니다.

CDN 서버에서 받아오기

IMQA WebAgent는 스크립트를 html의 <head> 내부 최상단에 삽입해 주셔야 합니다.

web-agent.js 연결 할 html <head>

// IMQA web-agent.js 연결
<script src="https://cdn.imqa.io/agent/web-agent.js"></script>

// IMQA web-agent 스크립트 필수 값
<script>
((w, c, _wv, _w, _wk, _mh, _b) => {
    w[c] = w[c] || {};
    function imqaConf(key, value){w[c][key]=value};

    imqaConf("imqaAgentUse", true);
    imqaConf("projectKey", "사용자 프로젝트키");

    w[_w](w);
})(window, 'imqaClientConfig', 'IMQAWebviewMain', 'IMQAWebMain', 'webkit', 'messageHandlers', 'ImqaBridge')
</script>

로컬에 설치하기

web-agent.js 연결 할 html <head>

// IMQA web-agent.js 연결
<script src="사용자 경로/web-agent.js"></script>

// IMQA web-agent 스크립트 필수 값
<script>
((w, c, _wv, _w, _wk, _mh, _b) => {
    w[c] = w[c] || {};
    function imqaConf(key, value){w[c][key]=value};

    imqaConf("imqaAgentUse", true);
    imqaConf("projectKey", "사용자 프로젝트키");

    w[_w](w);
})(window, 'imqaClientConfig', 'IMQAWebviewMain', 'IMQAWebMain', 'webkit', 'messageHandlers', 'ImqaBridge')
</script>

1.2. WPM / MPM 통합 사용 (WebAgent + WebviewAgent 설치)

WPM과 MPM 서비스를 이용하며, 모바일과 웹 브라우저 애플리케이션 구성에서의 웹뷰/웹 성능 분석을 위한 Agent 설치 방법입니다.

CDN 서버에서 받아오기

IMQA WebAgent는 스크립트를 html의 <head> 내부 최상단에 삽입해 주셔야 합니다.

web-agent.js 연결 할 html <head>

// IMQA web-agent.js 연결
<script src="https://cdn.imqa.io/agent/web-agent.js"></script>
<script src="https://cdn.imqa.io/agent/webview-agent.js"></script>

// IMQA web-agent 스크립트 필수 값
<script>
((w, c, _wv, _w, _wk, _mh, _b) => {
    w[c] = w[c] || {};
    function imqaConf(key, value){w[c][key]=value};

    imqaConf("imqaAgentUse", true);
    imqaConf("projectKey", "사용자 프로젝트키");
    if ((w[_wk] !== undefined && w[_wk][_mh] !== undefined) || w[_b] !== undefined)
      w[_wv](w);
    else w[_w](w);
})(window, 'imqaClientConfig', 'IMQAWebviewMain', 'IMQAWebMain', 'webkit', 'messageHandlers', 'ImqaBridge')
</script>

로컬에 설치하기

설치형 혹은 CDN으로 요청을 못하시는 경우 해당 스크립트를 다운로드 받아서 사용 가능합니다. 이 링크를 통해서 마우스 오른쪽 버튼을 누른 후 “다른 이름으로 저장”을 눌러서 연결해 주세요.

web-agent.js 연결 할 html <head>

// 로컬에 받은 IMQA web-agent.js 연결
<script src="사용자 경로/web-agent.js"></script>
<script src="사용자 경로/webview-agent.js"></script>

// IMQA web-agent 스크립트 필수 값
<script>
((w, c, _wv, _w, _wk, _mh, _b) => {
    w[c] = w[c] || {};
    function imqaConf(key, value){w[c][key]=value};

    imqaConf("imqaAgentUse", true);
    imqaConf("projectKey", "사용자 프로젝트키");
    if ((w[_wk] !== undefined && w[_wk][_mh] !== undefined) || w[_b] !== undefined)
      w[_wv](w);
    else w[_w](w);
})(window, 'imqaClientConfig', 'IMQAWebviewMain', 'IMQAWebMain', 'webkit', 'messageHandlers', 'ImqaBridge')
</script>

2. [공통] WebAgent 설정

IMQA WebAgent는 서비스마다 옵션을 다르게 주어 동작하게 할 수 있습니다.

2.1. 필수 설정

IMQA 사용 설정

IMQA WebAgent는 스크립트를 html의 <head> 내부 최상단에 삽입해 주셔야 합니다. 아래의 필수 옵션을 포함해야 정상적으로 동작합니다.

Option Name	Type	Default Value	Description
imqaAgentUse	boolean	true	true : IMQA WebAgent를 사용합니다. false : IMQA WebAgent를 사용하지 않습니다.
projectKey	string	“사용자 프로젝트 키”	IMQA에서 생성한 WPM 프로젝트의 키를 입력합니다.

Option Name

Type

Default Value

Description

imqaAgentUse

boolean

true

true : IMQA WebAgent를 사용합니다.

false : IMQA WebAgent를 사용하지 않습니다.

projectKey

string

“사용자 프로젝트 키”

IMQA에서 생성한 WPM 프로젝트의 키를 입력합니다.

필수 설정만 적용한 스크립트는 아래와 같습니다.

web-agent.js 연결 할 html <head>

// IMQA web-agent.js 연결
<script src="https://cdn.imqa.io/agent/web-agent.js"></script>
<script>
((w, c, _wv, _w, _wk, _mh, _b) => {
    w[c] = w[c] || {};
    function imqaConf(key, value){w[c][key]=value};

    imqaConf("imqaAgentUse", true); // IMQA Agent 사용여부
    imqaConf("projectKey", "사용자 프로젝트키"); // 사용자 프로젝트키

    w[_w](w);
})(window, 'imqaClientConfig', 'IMQAWebviewMain', 'IMQAWebMain', 'webkit', 'messageHandlers', 'ImqaBridge')
</script>

교차 도메인 설정

IMQA에서 분석할 메인 도메인 외에 교차 도메인을 설정할 수 있습니다. 서브 도메인 (예: m.imqa.io) 별도 구성되어 있을 경우나 CORS (교차 출처 리소스 공유) 접근이 필요할 경우 허용할 출처를 지정할 수 있습니다.

① IMQA WPM 프로젝트의 […] 아이콘 클릭 시 프로젝트 관리 메뉴를 표시합니다.

② [교차 도메인] 설정을 클릭합니다.

③ 기본 프로젝트 생성 시 입력한 메인 도메인 URL이 설정되어 있으며, 웹 사이트 구성에 따라 서브 도메인 또는 교차 출처 리소스 공유 접근을 허용할 출처를 입력합니다.

허용 도메인 설정 예시

허용 도메인 URL에 접근을 허용할 도메인 목록을 지정합니다. (예: http://localhost:8080)

1줄로 구분하여 입력할 수 있으며, 프로토콜 및 포트번호, 대소문자를 구분하고 * 문자를 포함할 수 없습니다.

④ 허용 도메인 목록을 입력하고 [저장]을 클릭합니다.

⑤ 입력한 허용 도메인 목록에서 실시간으로 데이터를 수집하도록 설정되며, IMQA에서 확인할 수 있습니다.

IMQA WebAgent는 기본적으로 사용자의 웹 브라우저 애플리케이션 구성에서 중요한 단위에서만 데이터 수집이 가능하도록 지원하며, 설치 코드 복제에 의한 라이선스 보호 등을 위하여 허용된 도메인에서만 데이터를 수집합니다. 메인 도메인 URL 외 성능 데이터 수집을 원하는 도메인이 있다면 교차 도메인 설정 기능을 통한 허용 도메인 목록 설정이 필요합니다.

URL 패턴 설정

웹 사이트 URL의 패턴을 찾고, 원하는 형태로 대체하여 IMQA로 수집할 수 있습니다. URL의 숫자, 식별자 (예: 유입ID, 사용자ID, 검색어 등) 대체나 유사한 페이지를 의미 있는 집계 단위로 묶을 수 있습니다.

IMQA WPM은 기본적으로 사용자가 접속한 원시 URL 데이터를 수집합니다. 사용자가 웹 사이트 이용시, 여러 식별자, 검색어 등으로 URL이 파편화 될 가능성이 높은 페이지의 경우 URL 패턴 설정을 통해 유의미한 집계/분석 단위 정의를 하시는 것을 권장합니다.

❶ URL 패턴 웹 사이트 URL의 경로 또는 쿼리 파라미터에서 원하는 형태로 대체할 패턴을 입력합니다. 경로와 쿼리 파라미터 단위를 입력할 수 있습니다. 우선순위가 높은 URL 패턴부터 적용되며, 쿼리 파라미터는 ’키=값’ 형태로 입력되어야 합니다.

1. 웹 사이트 URL 구성에 따라 경로 또는 쿼리 파라미터에서 묶고 싶은 단위에 변수 {group} 를 포함하여 입력합니다.

2. 웹 사이트 URL 구성에 따라 경로 또는 쿼리 파라미터에서 풀고 싶은 단위에 변수 {value} 를 포함하여 입력합니다.

3. URL 패턴을 입력하고 [+] 아이콘을 클릭합니다.

URL 패턴 설정 예시 1)
“상품 상세 페이지 URL인 ‘products’ 경로 다음의 숫자를 묶어서 하나의 페이지로 집계/분석하고 싶어요. 쿼리 파라미터는 상세하게 구분하지 않아도 돼요.”
1. 특정 ‘경로'에 적용할 URL 패턴을 변수 {group} 를 포함하여 입력합니다. 2. 설정 시점부터 수집되는 URL을 원하는 형태로 대체하여 IMQA에서 ‘페이지' 단위로 확인할 수 있습니다.
URL 패턴 설정 예시 2)
“메인 페이지로 유입되는 유형을 구분하고 싶어요. URL 쿼리 파라미터에 붙는 외부 유입ID ‘fbclid’, ‘NaPm’, ‘gclid’는 표시하고, 값은 상세하게 구분하지 않아도 돼요.”
1. 특정 ‘경로'와 ‘쿼리 파라미터’에 적용할 URL 패턴을 변수 {group} 를 포함하여 입력합니다.
2. 설정 시점부터 수집되는 URL을 원하는 형태로 대체하여 IMQA에서 ‘페이지' 단위로 확인할 수 있습니다.
URL 패턴 설정 예시 3)
“베스트 상품 목록 페이지에서 카테고리별 유형을 구분하고 싶어요. ‘best’ 경로의 URL 쿼리 파라미터에 붙는 카테고리ID ‘category_id’ 와 값을 구분하고, 나머지 쿼리 파라미터는 상세하게 구분하지 않아도 돼요.”
1. 특정 ‘경로'와 ‘쿼리 파라미터’에 적용할 URL 패턴을 변수 {value} 를 포함하여 입력합니다.
2. 설정 시점부터 수집되는 URL을 원하는 형태로 대체하여 IMQA에서 ‘페이지' 단위로 확인할 수 있습니다.

❷ 우선순위 URL 패턴을 적용할 순서를 나타냅니다. 우선순위가 높은 URL 패턴부터 적용되며, 순서를 변경할 수 있습니다.

우선순위 설정 예시)
“상품 상세 페이지 URL인 ‘products’ 경로 다음의 숫자를 묶는 패턴을 적용 중인데, 메인 ~ 상품 상세 페이지로 이동하는 유형인 내부 유입ID ‘flow’와 외부 유입ID ‘fbclid’로 접속하는 경우를 추가로 구분하고 싶어요.”
1. 우선순위가 높은 ‘경로'에 적용되는 URL 패턴이 우선 적용됩니다. 2. 특정 ‘경로'와 ‘쿼리 파라미터’에 적용할 URL 패턴의 우선순위를 높게 변경합니다.
3. 설정 이후, ‘쿼리 파라미터'에 적용되는 URL 패턴이 우선 적용되어 원하는 형태로 대체됩니다.

❸ URL 패턴 프로젝트에 설정된 전체 URL 패턴을 목록으로 표시합니다.

❹ 우선순위 변경 마우스 드래그로 URL 패턴 적용 순서를 조정할 수 있습니다.

❺ 삭제 추가한 URL 패턴을 삭제합니다. 삭제 시 해당 URL 패턴 항목이 삭제되며, 더 이상 URL 패턴이 적용되지 않습니다.

적용할 URL 패턴과 우선순위 설정이 끝나면 [저장]을 클릭합니다. 설정 시점부터 수집되는 URL을 원하는 형태로 대체하여 IMQA에서 ‘페이지' 단위로 확인할 수 있습니다.

2.2. [WPM] SPA 전용 옵션

SPA에서는 하나의 index.html을 기준으로 수집되기에 page 변경에 대한 이벤트가 없습니다. SPA 전용 옵션을 설정하여 path가 변경되었을 때 기준으로 일정 시간까지를 수집하실 수 있습니다. SPA에서는 path 변경 시 특정 DOM이 교체되므로, 이 특정 DOM을 Agent 옵션에 타겟으로 설정하면 정상적으로 SPA에서도 페이지 로딩시간을 수집할 수 있습니다.

Option Name	Type	Default Value	Description
SPACollectInitTime	number	3000	- 기본값: 3000 (3초) - SPA 성능 데이터 수집 간격을 ms(밀리초) 단위로 설정합니다. - path가 변경되면 설정된 수집 시간 동안 데이터를 수집합니다.
SPARootDom	string	“#app”	- CSS 셀렉터 스타일로 타겟이되는 DOM을 설정합니다. - 타겟이된 DOM 기준으로 DOM 변경을 감지합니다. (ID : #app, Class : .app) - 중복되는 셀렉터를 타겟으로 설정하면 정상적으로 수집이 되지 않습니다.

Option Name

Type

Default Value

Description

SPACollectInitTime

number

3000

- 기본값: 3000 (3초) - SPA 성능 데이터 수집 간격을 ms(밀리초) 단위로 설정합니다.

- path가 변경되면 설정된 수집 시간 동안 데이터를 수집합니다.

SPARootDom

string

“#app”

- CSS 셀렉터 스타일로 타겟이되는 DOM을 설정합니다.

- 타겟이된 DOM 기준으로 DOM 변경을 감지합니다.

(ID : #app, Class : .app)

- 중복되는 셀렉터를 타겟으로 설정하면 정상적으로 수집이 되지 않습니다.

필수 설정과 SPA 전용 옵션을 적용한 스크립트는 아래와 같습니다.

web-agent.js 연결 할 html <head>

// IMQA web-agent.js 연결
<script src="https://cdn.imqa.io/agent/web-agent.js"></script>
<script>
((w, c, _wv, _w, _wk, _mh, _b) => {
    w[c] = w[c] || {};
    function imqaConf(key, value){w[c][key]=value};

    // 필수 설정
    imqaConf("imqaAgentUse", true); // IMQA Agent 사용여부
    imqaConf("projectKey", "사용자 프로젝트키"); // 사용자 프로젝트키

    // SPA 전용 옵션 설정
    imqaConf("SPACollectInitTime", 5000); // SPA 수집시간설정
    imqaConf("SPARootDom", "#container"); // SPA ROOT DOM

    w[_w](w);
})(window, 'imqaClientConfig', 'IMQAWebviewMain', 'IMQAWebMain', 'webkit', 'messageHandlers', 'ImqaBridge')
</script>

2.3. [WPM] 행동분석 유지 시간 옵션

IMQA 행동분석에서 확인할 수 있는 사용자 행동 세션의 유지 시간을 설정 가능합니다. 세션은 기본 30분 동안 유지되며, 사용자가 30분 동안 페이지 이동이 없을 경우 종료됩니다.

컨텐츠 중심 웹 사이트와 같이 평균적으로 사용자가 웹 사이트에서 페이지 이동 없이 긴 시간 이용하는 경우, 세션이 종료되지 않도록 설정할 수 있습니다.

Option Name	Type	Default Value	Description
browserTxIdIntervalTime	number	1800000	- 기본값: 1800000 (30분) - 세션 유지 시간을 ms(밀리초) 단위로 설정합니다. - 유저의 행동 과정을 유지하는 ID 값 유지시간을 설정합니다.

Option Name

Type

Default Value

Description

browserTxIdIntervalTime

number

1800000

- 기본값: 1800000 (30분) - 세션 유지 시간을 ms(밀리초) 단위로 설정합니다.

- 유저의 행동 과정을 유지하는 ID 값 유지시간을 설정합니다.

필수 설정과 행동분석 유지 시간 옵션을 적용한 스크립트는 아래와 같습니다.

web-agent.js 연결 할 html <head>

// IMQA web-agent.js 연결
<script src="https://cdn.imqa.io/agent/web-agent.js"></script>
<script>
((w, c, _wv, _w, _wk, _mh, _b) => {
    w[c] = w[c] || {};
    function imqaConf(key, value){w[c][key]=value};

    // 필수 설정
    imqaConf("imqaAgentUse", true); // IMQA Agent 사용여부
    imqaConf("projectKey", "사용자 프로젝트키"); // 사용자 프로젝트키

    // 행동분석 유지 시간 옵션 설정
    imqaConf("browserTxIdIntervalTime", 3600000); // 행동분석 유지 시간 (1시간)

    w[_w](w);
})(window, 'imqaClientConfig', 'IMQAWebviewMain', 'IMQAWebMain', 'webkit', 'messageHandlers', 'ImqaBridge')
</script>

2.4. [WPM] 스크립트 실행시간 측정

IMQA 타임라인에서 javascript에서 특정 로직의 작업시간을 체크할 수 있습니다. Performance 표준인 mark, measure를 사용하면 손쉽게 추적이 가능합니다. 각 mark와 measure 안에 들어가는 텍스트는 중복되지 않는 고유한 텍스트로 정의해 주세요.

프레임워크의 코어에 적용 시 추적되는 코드가 비정상적으로 늘어나 메모리 누수가 생길 수 있으니 주의해 주세요.

① 실행시간 측정을 원하는 스크립트의 상단과 하단에 Performance.mark와 measure를 정의합니다.

Performance.mark, measure 예시코드


<script>
  function fun1(){
    performance.mark("fun1-start")

    // 성능을 측정할 코드…

    performance.mark("fun1-end")
    performance.measure("fun1-measure", "fun1-start", "fun1-end")
  }
</script>

② ‘페이지 로딩시간 분석’ 팝업 스크립팅 섹션에서 마킹한 스크립트를 확인할 수 있으며 해당 스크립트 실행시간이 표시됩니다.

아래와 같이 특정 스크립트의 실행 시간도 측정할 수 있습니다.

2.5. [WCrash] Custom Web Crash 발생

IMQA WebAgent 에서는 상세한 웹 에러 분석을 위해 원하는 에러 메시지를 지정하여 사용자 정의 에러를 수집할 수 있습니다.

사용자 정의 에러 생성

IMQA WCrash는 사용자가 정의한 에러를 감지하여 수집합니다.

다른 에러 일지라도 같은 에러 타입일 경우, 동일 에러로 인식하여 에러가 누적될 경우가 생길 수 있습니다.

사용자 정의 에러 메시지 지정

WebAgent에서 수집하는 기본 에러 메시지를 원하는 에러 메시지로 변경하여 수집할 수 있습니다. 상세한 웹 에러 분석을 위해 에러 메시지를 지정하는 것을 권장드립니다.

에러 메시지를 지정하는 경우, 같은 에러 타입일지라도 다른 에러로 수집됩니다.

사용자 정의 에러 수집할 js 파일

...
// try catch를 사용할 경우
try {
	...
}
catch(e){
	throw new Error("사용자가 지정한 에러 메시지");
}

// 기본 Error를 생성할 경우
new Error("사용자가 지정한 에러 메시지");

웹 크래시 분석

아래와 같이 IMQA WCrash 서비스에서 웹 크래시를 상세한 정보와 함께 확인할 수 있습니다.

❶ 캐치된 에러 인스턴스 타입 웹 페이지에서 에러가 생성되었을 경우 해당 에러의 캐치된 에러 인스턴스명을 표시합니다.

에러 타입	설명
Error	사용자가 설정한 에러 타입입니다.
EvalError	eval()에서 발생하는 오류입니다.
RangeError	변수의 유효한 범위를 벗어났을 경우 생성되는 오류입니다.
ReferenceError	잘못된 참조를 했을 경우 생성되는 오류입니다.
SyntaxError	잘못된 구문이 존재하는 경우 오류입니다.
TypeError	유효한 자료형이 아닐 경우 해당 타입의 오류입니다.
URIError	encodeURI()나 decodeURI() 함수에 부적절한 매개변수를 넘겨준 경우 생성되는 오류입니다.
AggregateError	여러 오류를 하나의 오류로 감싸는 오류 형태입니다.

에러 타입

설명

Error

사용자가 설정한 에러 타입입니다.

EvalError

eval()에서 발생하는 오류입니다.

RangeError

변수의 유효한 범위를 벗어났을 경우 생성되는 오류입니다.

ReferenceError

잘못된 참조를 했을 경우 생성되는 오류입니다.

SyntaxError

잘못된 구문이 존재하는 경우 오류입니다.

TypeError

유효한 자료형이 아닐 경우 해당 타입의 오류입니다.

URIError

encodeURI()나 decodeURI() 함수에 부적절한 매개변수를 넘겨준 경우 생성되는 오류입니다.

AggregateError

여러 오류를 하나의 오류로 감싸는 오류 형태입니다.

❷ 사용자 정의 에러 메시지 특정 에러 타입 에러가 생성될 때 사용자가 지정한 메시지를 표시합니다.

throw new Error("사용자가 지정한 에러 메시지");

3. [공통] 브라우저 호환성

IMQA WebAgent는 아래의 브라우저 또는 브라우저 버전에서 성능 데이터를 수집/측정하며, 호환되지 않는 브라우저 또는 브라우저 버전에 따라 정상적으로 데이터가 수집/측정이 되지 않을 수 있습니다.

수집 데이터	Chrome	Edge	Firefox	Opera	Safari
페이지 로드	>10	>12	>7	>15	>15
리소스 로드	>28	>12	>35	>15	>11
네트워크 요청	>43	>12	>31	>30	>11
Core Web Vitals	>77	>79	FID only	>64	FID only
SPA 로드	>26	>12	>14	>15	>7
스크립트 실행시간 측정	>28	>12	>38	>15	>11

수집 데이터

Chrome

Edge

Firefox

Opera

Safari

페이지 로드

>10

>12

>15

리소스 로드

>28