이 SDK는 GitLab 제품 분석 기능에 데이터를 전송하도록 웹사이트 및 애플리케이션을 계측하기 위한 것입니다.

Browser SDK 사용 방법#

NPM 패키지 사용#

선호하는 패키지 매니저를 사용하여 package 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>

Browser SDK 초기화 옵션#

appId와 host 외에도 다음 옵션으로 Browser SDK를 구성할 수 있습니다:

interface GitLabClientSDKOptions {
  appId: string;
  host: string;
  hasCookieConsent?: boolean;
  trackerId?: string;
  pagePingTracking?:
    | boolean
    | {
        minimumVisitLength?: number;
        heartbeatDelay?: number;
      };
  plugins?: AllowedPlugins;
}

플러그인#

• 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"
      }
   ]
}

• Link Click Tracking: 이 플러그인을 사용하면 트래커가 모든 링크 요소에 클릭 이벤트 리스너를 추가합니다. 링크 클릭은 자기 설명적(self-describing) 이벤트로 추적됩니다. 각 링크 클릭 이벤트는 링크의 href 속성을 캡처합니다. 이벤트에는 링크의 ID, 클래스, target(새 탭이나 새 창과 같이 연결된 문서가 열리는 위치)에 대한 필드도 포함됩니다.

• 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);

page#

페이지뷰 이벤트를 트리거하는 데 사용됩니다.

glClient.page(eventAttributes);

eventAttributes 객체는 다음과 같은 선택적 속성을 지원합니다:

track#

커스텀 이벤트를 트리거하는 데 사용됩니다.

glClient.track(eventName, eventAttributes);

refreshLinkClickTracking#

enableLinkClickTracking은 페이지가 로드될 때 존재하는 링크의 클릭만 추적합니다. 페이지가 로드된 후 추가된 새 링크를 추적하려면 refreshLinkClickTracking을 사용하세요.

glClient.refreshLinkClickTracking();

trackError#

trackError는 Browser SDK에서 지원되지만, 결과 이벤트는 사용되거나 사용 가능하지 않습니다.

오류를 캡처하는 데 사용됩니다. 이는 errorTracking 플러그인이 활성화된 경우에만 작동합니다. 플러그인은 기본적으로 활성화되어 있습니다.

glClient.trackError(eventAttributes);

예를 들어, trackError는 다음과 같이 try...catch에서 사용할 수 있습니다:

try {
  // Call the function that throws an error
  throwError();
} catch (error) {
  glClient.trackError({
    message: error.message, // "This is a custom error"
    filename: error.fileName || 'unknown', // The file in which the error occurred (for example, "index.html")
    lineno: error.lineNumber || 0, // The line number where the error occurred (for example, 2)
    colno: error.columnNumber || 0, // The column number where the error occurred (for example, 6)
    error: error, // The Error object itself
  });
}

addCookieConsent#

addCookieConsent는 쿠키를 통한 사용자 식별자 추적을 허용하는 데 사용됩니다. 기본적으로 hasCookieConsent는 false이며, 사용자 식별자가 전달되지 않습니다. 사용자 식별자 추적을 활성화하려면 addCookieConsent 메서드를 호출하세요. hasCookieConsent를 true로 설정하여 Browser SDK를 초기화한 경우에는 이 단계가 필요하지 않습니다.

glClient.addCookieConsent();

setCustomUrl#

추적을 위한 커스텀 URL을 설정하는 데 사용됩니다.

glClient.setCustomUrl(url);

setReferrerUrl#

추적을 위한 리퍼러 URL을 설정하는 데 사용됩니다.

glClient.setReferrerUrl(url);

setDocumentTitle#

문서 제목을 재정의하는 데 사용됩니다.

glClient.setDocumentTitle(title);

기여#

Browser SDK에 기여하고 싶다면 기여 가이드를 따르세요.

트러블슈팅#

Browser SDK가 이벤트를 전송하지 않거나 예상치 못한 방식으로 동작하는 경우 다음 조치를 취하세요:

• options 객체의 appId 및 host 값이 올바른지 확인하세요.

• 브라우저 개인 정보 보호 설정, 확장 프로그램, 또는 광고 차단기가 Browser SDK를 방해하고 있는지 확인하세요.

자세한 정보와 지원은 Snowplow 문서를 참조하거나 Analytics Instrumentation 팀에 문의하세요.