• 브라우저 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 플러그인이 활성화된 경우에만 작동합니다. plugin는 기본적으로 활성화됩니다.

glClient.trackError(eventAttributes);

예를 들어, trackError는 아래와 같이 try...catch에서 사용될 수 있습니다.

try {
  // 오류를 발생시키는 함수 호출
  throwError();
} catch (error) {
  glClient.trackError({
    message: error.message, // "This is a custom error"
    filename: error.fileName || 'unknown', // 오류가 발생한 파일 (예: "index.html")
    lineno: error.lineNumber || 0, // 오류가 발생한 행 번호 (예: 2)
    colno: error.columnNumber || 0, // 오류가 발생한 열 번호 (예: 6)
    error: error, // 오류 객체 자체
  });
}

addCookieConsent

addCookieConsent는 쿠키를 통해 사용자 식별자를 추적할 수 있도록 하는 데 사용됩니다. 기본적으로 hasCookieConsent이 false이며 사용자 식별자가 전달되지 않습니다. 사용자 식별자의 추적을 활성화하려면 addCookieConsent 메서드를 호출하세요. 브라우저 SDK를 hasCookieConsent로 초기화했다면 이 단계가 필요하지 않습니다.

glClient.addCookieConsent();

setCustomUrl

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

glClient.setCustomUrl(url);

setReferrerUrl

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

glClient.setReferrerUrl(url);

setDocumentTitle

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

glClient.setDocumentTitle(title);

기여하기

브라우저 SDK에 기여하고 싶다면 기여 가이드를 따르세요.

문제 해결

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

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

자세한 정보 및 지원은 Snowplow documentation 을 참조하거나 Analytics Instrumentation team에 문의하세요.