브라우저 SDK
이 SDK는 웹 사이트 및 응용 프로그램에 데이터를 보내기 위한 GitLab 제품 분석 기능을 위한 것입니다.
브라우저 SDK 사용 방법
NPM 패키지 사용
선호하는 패키지 관리자를 사용하여 NPM 패키지를 패키지 JSON에 추가합니다:
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
| 활성화 또는 비활성화할 플러그인을 지정합니다. 기본적으로 모든 플러그인이 활성화되어 있습니다. |
플러그인
-
Client Hints
: 사용자 에이전트를 추적하는 대신 사용자 에이전트 문자열을 동결하는 브라우저에서 특히 유용한 대안입니다. 이 플러그인을 활성화하면 다음과 같은 컨텍스트가 자동으로 캡처됩니다:예를 들어, iglu:org.ietf/http_client_hints/jsonschema/1-0-0에는 다음과 같은 구성이 있습니다:
{ "isMobile":false, "brands":[ { "brand":"Google Chrome", "version":"89" }, { "brand":"Chromium", "version":"89" } ] }
-
Link Click Tracking
: 이 플러그인을 사용하면 추적기가 모든 링크 요소에 클릭 이벤트 리스너를 추가합니다. 링크 클릭은 자체 설명형 이벤트로 추적됩니다. 각 링크 클릭 이벤트는 링크의href
속성을 캡처합니다. 이 이벤트에는 링크의 ID, 클래스 및 대상(링크된 문서가 열리는 위치, 예를 들어 새 탭 또는 새 창)에 대한 필드도 포함됩니다. -
Performance Timing
: 이 플러그인은 사용자 브라우저에서Navigation Timing API
를 사용하여 사용자의 성능 관련 데이터를 수집합니다. 이 API는 웹 페이지를로드하는 다양한 단계에 대한 상세 정보를 제공하므로 도메인 조회, 연결 시간, 콘텐츠 다운로드 및 렌더링 시간 등과 같은 정보를 제공합니다. 이 플러그인은 사용자가 웹 사이트에 대한 성능에 대한 통찰을 제공하고 잠재적 성능 병목 현상을 식별하고 전반적인 사용자 경험을 개선하는 데 도움이 됩니다. -
Error Tracking
: 이 플러그인은 웹 사이트나 응용 프로그램에서 발생한 오류를 캡처하고 추적하는 데 도움이 됩니다. 이러한 오류를 모니터링함으로써 코드 또는 타사 라이브러리와 관련된 잠재적인 문제에 대한 통찰을 얻어 웹 사이트나 응용 프로그램의 전반적인 사용자 경험을 개선하고 품질을 유지할 수 있습니다.
기본적으로 모든 플러그인이 활성화되어 있습니다. 이러한 플러그인을 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);
예를 들어, 다음과 같이 try...catch
에서 trackError
를 사용할 수 있습니다.
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
| 추적된 이벤트에 추가해야 하는 이벤트 속성입니다. eventAttributes 에서 message 는 필수 키입니다.
|
addCookieConsent
addCookieConsent
는 쿠키를 통해 사용자 식별을 추적할 수 있도록 사용됩니다. 기본적으로 hasCookieConsent
는 false이며 사용자 식별자가 전달되지 않습니다. 사용자 식별을 추적하려면 addCookieConsent
메서드를 호출하세요. 브라우저 SDK를 hasCookieConsent
로 초기화했다면이 단계가 필요하지 않습니다.
glClient.addCookieConsent();
setCustomUrl
추적을 위해 사용자 정의 URL을 설정하는 데 사용됩니다.
glClient.setCustomUrl(url);
속성 | 유형 | 설명 |
---|---|---|
url
| String
| 추적을 위해 설정하려는 사용자 정의 URL입니다. |
setReferrerUrl
추적을 위해 referrer URL을 설정하는 데 사용됩니다.
glClient.setReferrerUrl(url);
속성 | 유형 | 설명 |
---|---|---|
url
| String
| 추적을 위해 설정하려는 referrer URL입니다. |
setDocumentTitle
문서 제목을 덮어쓰기하는 데 사용됩니다.
glClient.setDocumentTitle(title);
속성 | 유형 | 설명 |
---|---|---|
title
| String
| 설정하려는 문서 제목입니다. |
기여하기
만약 Browser SDK에 기여하고 싶다면, 기여 가이드를 따르세요.
문제 해결
만약 브라우저 SDK가 이벤트를 보내지 않거나 예상치 못한 방식으로 작동하지 않는다면, 다음 조치를 취하세요:
- 옵션 개체의
appId
및 호스트 값이 올바른지 확인합니다. - 브라우저 개인 정보 보호 설정, 확장 프로그램 또는 광고 차단기가 브라우저 SDK와 간섭하는지 확인합니다.
더 많은 정보와 지원이 필요하다면, Snowplow 문서를 참조하거나 Analytics Instrumentation team에 연락하세요.