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

브라우저 SDK

이 SDK는 웹 사이트 및 응용 프로그램을 계기로하여 GitLab 제품 분석 기능에 데이터를 전송하는 것을 위한 것입니다.

브라우저 SDK 사용 방법

NPM 패키지 사용

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

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

• Link Click Tracking: 이 플러그인을 사용하면 추적기는 모든 링크 요소에 클릭 이벤트 리스너를 추가합니다. 링크 클릭은 self-describing 이벤트로 추적됩니다. 각 링크 클릭 이벤트는 링크의 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

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

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를 true로 설정하여 초기화했다면 이 단계는 필요하지 않습니다.

glClient.addCookieConsent();

setCustomUrl

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

glClient.setCustomUrl(url);

setReferrerUrl

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

glClient.setReferrerUrl(url);

setDocumentTitle

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

glClient.setDocumentTitle(title);

기여하기

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

문제 해결

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

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

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