• 브라우저 SDK 사용 방법
  • NPM 패키지 사용하기
  • 스크립트 직접 사용하기
• 브라우저 SDK 초기화 옵션
  • 플러그인
• 방법
  • identify
  • page
  • track
  • refreshLinkClickTracking
  • trackError
  • addCookieConsent
  • setCustomUrl
  • setReferrerUrl
  • setDocumentTitle
• 기여하기
• 문제 해결

브라우저 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;
}

플러그인

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

page

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

glClient.page(eventAttributes);

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

track

사용자 정의 이벤트를 트리거하는 데 사용됩니다.

glClient.track(eventName, eventAttributes);

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, // 오류 객체 자체
  });
}

addCookieConsent

addCookieConsent는 쿠키를 통해 사용자 식별자의 추적을 허용하는 데 사용됩니다.

기본적으로 hasCookieConsent는 false이며, 사용자 식별자가 전달되지 않습니다.

사용자 식별자의 추적을 활성화하려면 addCookieConsent 메서드를 호출하세요.

hasCookieConsent를 true로 설정하여 브라우저 SDK를 초기화한 경우 이 단계가 필요하지 않습니다.

glClient.addCookieConsent();

setCustomUrl

추적을 위한 사용자 지정 URL을 설정하는 데 사용됩니다.

glClient.setCustomUrl(url);

setReferrerUrl

추적을 위한 참고 URL을 설정하는 데 사용됩니다.

glClient.setReferrerUrl(url);

setDocumentTitle

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

glClient.setDocumentTitle(title);

기여하기

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

문제 해결

브라우저 SDK가 이벤트를 보내지 않거나 예상치 못한 방식으로 동작하는 경우, 다음 조치를 취하세요:

1. 옵션 객체의 appId 및 호스트 값이 올바른지 확인하세요.
2. 브라우저의 개인 정보 설정, 확장 프로그램 또는 광고 차단기가 브라우저 SDK에 영향을 미치고 있는지 확인하세요.

더 많은 정보와 지원이 필요하다면, Snowplow 문서를 참고하거나 분석 기기 팀에 문의하세요.