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 프로젝트의 키를 입력합니다.

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

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)

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

필수 설정과 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 값 유지시간을 설정합니다.

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

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. [WPM] WebAgent Console.log 표시 옵션

IMQA WebAgent의 콘솔 로그를 표시하거나 끌 수 있습니다.

Option Name

Type

Default Value

Description

imqa_log

boolean

true

- true: IMQA WebAgent의 콘솔 로그를 표시합니다.

- false: IMQA WebAgent의 콘솔 로그를 표시하지 않습니다.

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

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", "사용자 프로젝트키"); // 사용자 프로젝트키

    // console.log 표시 옵션 설정
    imqaConf("imqa_log", false); // IMQA Agent 콘솔 로그 끔

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

2.6. [WPM] 수집 서버 설정

설치형으로 진행 된 고객사에서는 반드시 이 부분 설정이 필요합니다.

IMQA MPM 프레임워크가 수집하는 데이터를 보내는 수집 서버를 별도로 설정하실 수 있습니다. 기본적으로는 SaaS 서비스를 이용하는 고객은 별도 설정이 필요하지 않습니다.

Option Name

Type

Default Value

Description

collectorHost

string

main.collector.imqa.io

수집 서버의 호스트를 설정합니다.

protocol

string

https

수집 서버의 프로토콜을 설정합니다.

필수 설정과 수집 서버 설정을 적용한 스크립트는 아래와 같습니다.

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", "사용자 프로젝트키"); // 사용자 프로젝트키

    // 수집 서버 URL 설정
    imqaConf("collectorHost", "121.0.136.28:3980"); // 수집 서버 호스트 (기본값: 'main.collector.imqa.io')
    imqaConf("protocol", "http"); // 수집 서버 프로토콜 (기본값: 'https')

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

2.7. [WCrash] Custom Web Crash 발생

IMQA WebAgent 에서는 웹 페이지에서 발생하는 에러나 비즈니스 로직에서 발생하는 다양한 문제를 사용자 정의 에러로 수집할 수 있습니다.

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

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

try {
	...
} catch (e) {
	throw new IMQACustomError(e)
}

커스텀 웹 에러 발생시, 아래와 같이 IMQA Crash, WCrash 에러 검색에서 에러 유형 ‘WCustom’으로 구분하여 검색하실 수 있습니다.

현재 WCustom 유형 에러 목록 확인은 ‘에러 검색’ 페이지를 통해서만 가능합니다.

2.8. [WCrash] 특정 웹 크래시 수집 제한 옵션

IMQA WebAgent로 수집하고 싶지 않은 에러를 설정할 수 있습니다.

Option Name

Type

Default Value

Description

filterError

string[] | null

null

예) [”$”, “type”] - Agent가 수집한 에러(Web Crash)중 배열속 문자열이 포함된 에러라면 수집하지 않습니다. - 대소문자는 구분하지 않습니다. - [”type”]으로 옵션값을 설정하시면 “TypeError …”과 같은 에러도 수집되지 않습니다.

필수 설정과 특정 웹 크래시 수집 제한 옵션을 적용한 스크립트는 아래와 같습니다.

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("filterError", ["$", "type"]); // "$" 또는 "type"이 에러명에 포함된 에러는 수집하지 않음

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