• 브라우저 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: 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);

page

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

glClient.page(eventAttributes);

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

track

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

glClient.track(eventName, eventAttributes);

refreshLinkClickTracking

enableLinkClickTracking는 페이지가 로드된 후에 일어난 링크 클릭만 추적합니다. 페이지가 로드된 후에 추가된 새 링크를 추적하려면 refreshLinkClickTracking을 사용하십시오.

glClient.refreshLinkClickTracking();

trackError

오류를 캡처하는 데 사용됩니다. 이 기능은 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 메서드를 호출하세요. 브라우저 SDK를 hasCookieConsent를 true로 설정하여 초기화했다면 이 단계는 필요하지 않습니다.

glClient.addCookieConsent();

setCustomUrl

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

glClient.setCustomUrl(url);

setReferrerUrl

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

glClient.setReferrerUrl(url);

setDocumentTitle

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

glClient.setDocumentTitle(title);

기여

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

문제 해결

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

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

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