브라우저 SDK
이 SDK는 웹 사이트와 애플리케이션을 계기로하여 GitLab 제품 분석 기능에 데이터를 보내기 위한 것입니다.
브라우저 SDK 사용 방법
NPM 패키지 사용
선호하는 패키지 관리자를 사용하여 패키지 JSON에 NPM 패키지를 추가하십시오:
yarn add @gitlab/application-sdk-browser
npm i @gitlab/application-sdk-browser
그런 다음, 브라우저 사용을 위해 클라이언트 SDK를 가져오십시오:
import { glClientSDK } from '@gitlab/application-sdk-browser';
this.glClient = glClientSDK({ appId, host });
직접 스크립트 사용
스크립트를 페이지에 추가하고 클라이언트 SDK를 window
에 할당하십시오:
<script src="https://unpkg.com/@gitlab/application-sdk-browser/dist/gl-sdk.min.js"></script>
<script>
window.glClient = window.glSDK.glClientSDK({
appId: 'YOUR_APP_ID',
host: 'YOUR_HOST',
});
</script>
다음과 같이 SDK의 특정 버전을 사용할 수 있습니다:
<script src="https://unpkg.com/@gitlab/application-sdk-browser@0.2.5/dist/gl-sdk.min.js"></script>
브라우저 SDK 초기화 옵션
appId
와 host
외에 아래 옵션을 사용하여 브라우저 SDK를 구성할 수 있습니다:
interface GitLabClientSDKOptions {
appId: string;
host: string;
hasCookieConsent?: boolean;
trackerId?: string;
pagePingTracking?:
| boolean
| {
minimumVisitLength?: number;
heartbeatDelay?: number;
};
plugins?: AllowedPlugins;
}
옵션 | 설명 |
---|---|
appId
| GitLab 프로젝트 분석 설치 가이드에서 제공하는 ID입니다. 이 ID는 데이터가 분석 인스턴스로 전송되도록 보장합니다. |
host
| 설정 가이드에서 제공하는 GitLab 프로젝트 분석 인스턴스입니다. |
hasCookieConsent
| 고유한 사용자를 식별하는 데 쿠키를 사용할지 여부입니다. 기본값은 false 입니다. false 로 설정하면 사용자가 익명 사용자로 간주됩니다. 사용자를 식별하기 위해 쿠키나 다른 저장 메커니즘이 사용되지 않습니다.
|
trackerId
| 동일한 페이지나 애플리케이션에서 실행되는 여러 추적기를 구분하는 데 사용됩니다. 각 추적기 인스턴스는 다른 데이터 집합을 캡처하기 위해 구성될 수 있습니다. 이 식별자는 데이터가 수집기에 올바르게 연관되도록 돕습니다. 기본값은 gitlab 입니다.
|
pagePingTracking
| 사용자가 페이지를 활발하게 탐색하는 동안 주기적인 이벤트를 보내어 웹 사이트나 애플리케이션의 사용자 참여도를 추적할 수 있는 옵션입니다. pagePingTracking 은 부울 또는 객체일 수 있습니다. 부울로 설정하면 기본 옵션으로 페이지 핑을 활성화합니다. false 로 설정하면 페이지 핑 추적을 비활성화합니다. 객체로 설정하면 minimumVisitLength (첫 번째 하트비트가 발생하기까지 경과해야 하는 최소 시간)와 heartbeatDelay (콜백이 발생하는 간격) 두 가지 옵션이 있습니다.
|
plugins
| 기본적으로 모든 플러그인이 활성화됩니다. 플러그인을 활성화하거나 비활성화하려면 plugins 객체를 사용하십시오.
|
플러그인
-
Client Hints
: User Agent를 추적하는 대안으로, 특히 User Agent 문자열을 동결시키는 브라우저에서 유용합니다. 이 플러그인을 활성화하면 자동으로 다음 컨택스트를 캡처합니다:예를 들면, iglu:org.ietf/http_client_hints/jsonschema/1-0-0에는 다음과 같은 구성이 있습니다:
{ "isMobile":false, "brands":[ { "brand":"Google Chrome", "version":"89" }, { "brand":"Chromium", "version":"89" } ] }
-
링크 클릭 추적
: 이 플러그인을 사용하면 트래커가 모든 링크 요소에 대한 클릭 이벤트를 추가합니다. 링크 클릭은 자기 서술적인 이벤트로 추적됩니다. 각 링크 클릭 이벤트는 링크의href
속성을 캡처합니다. 이벤트에는 링크의 ID, 클래스, 대상(문서가 열리는 위치, 새 탭 또는 새 창과 같은)에 대한 필드도 포함됩니다. -
성능 타이밍
:Navigation Timing API
를 사용하여 사용자 브라우저에서 성능 관련 데이터를 수집합니다. 이 API는 웹 페이지 로딩의 다양한 단계에 대한 상세한 정보를 제공합니다. 도메인 조회, 연결 시간, 콘텐츠 다운로드, 렌더링 시간 등에 대한 자세한 정보를 제공합니다. 이 플러그인은 사용자가 웹 사이트를 얼마나 잘 사용하고 있는지에 대한 통찰을 얻고, 잠재적인 성능 병목 현상을 식별하고, 전반적인 사용자 경험을 개선하는 데 도움이 됩니다. -
오류 추적
: 웹 사이트나 애플리케이션에서 발생하는 오류를 캡처하고 추적하는 데 도움이 됩니다. 이러한 오류를 모니터링함으로써 코드나 타사 라이브러리와 관련된 잠재적인 문제에 대한 통찰을 얻을 수 있습니다. 이를 통해 전반적인 사용자 경험을 개선하고 웹 사이트나 애플리케이션의 품질을 유지할 수 있습니다.
기본적으로 모든 플러그인이 활성화됩니다. plugins
객체를 통해 이러한 플러그인을 비활성화하거나 활성화할 수 있습니다:
const tracker = glClientSDK({
...options,
plugins: {
clientHints: true,
linkTracking: true,
performanceTiming: true,
errorTracking: true,
},
});
메서드
identify
사용자와 사용자 속성을 세션과 추적 이벤트와 관련시키는 데 사용됩니다.
glClient.identify(userId, userAttributes);
속성 | 유형 | 설명 |
---|---|---|
userId
| String
| 응용프로그램이 개별 사용자를 식별하는 데 사용하는 사용자 식별자입니다. |
userAttributes
|
Object /Null /undefined
| 세션 및 추적 이벤트에 추가해야 하는 사용자 속성입니다. |
page
페이지뷰 이벤트를 트리거하는 데 사용됩니다.
glClient.page(eventAttributes);
속성 | 유형 | 설명 |
---|---|---|
eventAttributes
|
Object /Null /undefined
| 페이지뷰 이벤트에 추가해야 하는 이벤트 속성입니다. |
eventAttributes
객체는 다음과 같은 선택적 속성을 지원합니다:
속성 | 유형 | 설명 |
---|---|---|
title
| String
| 기본 페이지 제목 덮어쓰기 |
contextCallback
| Function
| 페이지 뷰에서 콜백 실행 |
context
| Object
| 페이지 뷰에 컨텍스트(추가 정보) 추가 |
timestamp
| timestamp
| 이벤트의 진짜 타임스탬프 설정 또는 장치가 보낸 타임스탬프 덮어쓰기 |
track
사용자 정의 이벤트를 트리거하는 데 사용됩니다.
glClient.track(eventName, eventAttributes);
속성 | 유형 | 설명 |
---|---|---|
eventName
| String
| 사용자 정의 이벤트의 이름 |
eventAttributes
|
Object /Null /undefined
| 추적된 이벤트에 추가해야 하는 이벤트 속성입니다. |
refreshLinkClickTracking
enableLinkClickTracking
는 페이지가 로드된 후에 일어난 링크 클릭만 추적합니다. 페이지가 로드된 후에 추가된 새 링크를 추적하려면 refreshLinkClickTracking
을 사용하십시오.
glClient.refreshLinkClickTracking();
trackError
trackError
는 브라우저 SDK에서 지원되지만 결과 이벤트는 사용되지 않거나 사용할 수 없습니다.오류를 캡처하는 데 사용됩니다. 이 기능은 errorTracking
플러그인이 활성화된 경우에만 작동합니다. 플러그인은 기본적으로 활성화되어 있습니다.
glClient.trackError(eventAttributes);
예를 들어, trackError
는 다음과 같이 try...catch
에서 사용될 수 있습니다:
try {
// 오류를 발생시키는 함수 호출
throwError();
} catch (error) {
glClient.trackError({
message: error.message, // "이것은 사용자 정의 오류입니다"
filename: error.fileName || 'unknown', // 오류가 발생한 파일(예: "index.html")
lineno: error.lineNumber || 0, // 오류가 발생한 라인 번호(예: 2)
colno: error.columnNumber || 0, // 오류가 발생한 열 번호(예: 6)
error: error, // 오류 객체 그 자체
});
}
속성 | 유형 | 설명 |
---|---|---|
eventAttributes
| Object
| 추적된 이벤트에 추가해야 하는 이벤트 속성입니다. message 는 eventAttributes 의 필수 키입니다.
|
addCookieConsent
addCookieConsent
은 쿠키를 통한 사용자 식별자 추적을 허용하는 데 사용됩니다. 기본적으로 hasCookieConsent
는 false이며 사용자 식별자가 전달되지 않습니다. 사용자 식별자의 추적을 활성화하려면 addCookieConsent
메서드를 호출하세요. 브라우저 SDK를 hasCookieConsent
를 true로 설정하여 초기화했다면 이 단계는 필요하지 않습니다.
glClient.addCookieConsent();
setCustomUrl
추적을 위한 사용자 정의 URL을 설정하는 데 사용됩니다.
glClient.setCustomUrl(url);
속성 | 타입 | 설명 |
---|---|---|
url
| String
| 추적을 위해 설정하려는 사용자 정의 URL. |
setReferrerUrl
추적을 위한 참조 URL을 설정하는 데 사용됩니다.
glClient.setReferrerUrl(url);
속성 | 타입 | 설명 |
---|---|---|
url
| String
| 추적을 위해 설정하려는 참조 URL. |
setDocumentTitle
문서 제목을 재정의하는 데 사용됩니다.
glClient.setDocumentTitle(title);
속성 | 타입 | 설명 |
---|---|---|
title
| String
| 설정하려는 문서 제목. |
기여
브라우저 SDK에 기여하고 싶다면 기여 가이드를 따르세요.
문제 해결
브라우저 SDK가 이벤트를 보내지 않거나 예상치 못한 방식으로 작동하는 경우 다음 조치를 취하세요:
- 옵션 객체의
appId
및 호스트 값이 올바른지 확인합니다. - 브라우저 개인 정보 보호 설정, 확장 프로그램 또는 광고 차단 프로그램이 브라우저 SDK와 간섭하는지 확인합니다.
더 자세한 정보와 지원이 필요한 경우 Snowplow 문서를 참조하거나 분석 계기팀에 문의하세요.