브라우저 SDK

이 SDK는 웹 사이트와 애플리케이션을 계기로하여 GitLab 제품 분석 기능에 데이터를 보내기 위한 것입니다.

브라우저 SDK 사용 방법

NPM 패키지 사용

선호하는 패키지 관리자를 사용하여 패키지 JSON에 NPM 패키지를 추가하십시오:

yarn
yarn add @gitlab/application-sdk-browser
npm
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 초기화 옵션

appIdhost 외에 아래 옵션을 사용하여 브라우저 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

note
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 추적된 이벤트에 추가해야 하는 이벤트 속성입니다. messageeventAttributes의 필수 키입니다.

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가 이벤트를 보내지 않거나 예상치 못한 방식으로 작동하는 경우 다음 조치를 취하세요:

  1. 옵션 객체의 appId 및 호스트 값이 올바른지 확인합니다.
  2. 브라우저 개인 정보 보호 설정, 확장 프로그램 또는 광고 차단 프로그램이 브라우저 SDK와 간섭하는지 확인합니다.

더 자세한 정보와 지원이 필요한 경우 Snowplow 문서를 참조하거나 분석 계기팀에 문의하세요.