• 브라우저 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: 사용자 에이전트를 추적하는 대신 사용자 에이전트 문자열을 동결하는 브라우저에서 특히 유용한 대안입니다. 이 플러그인을 활성화하면 다음과 같은 컨텍스트가 자동으로 캡처됩니다:

  예를 들어, 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);

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

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로 초기화했다면이 단계가 필요하지 않습니다.

glClient.addCookieConsent();

setCustomUrl

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

glClient.setCustomUrl(url);

setReferrerUrl

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

glClient.setReferrerUrl(url);

setDocumentTitle

문서 제목을 덮어쓰기하는 데 사용됩니다.

glClient.setDocumentTitle(title);

기여하기

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

문제 해결

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

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

더 많은 정보와 지원이 필요하다면, Snowplow 문서를 참조하거나 Analytics Instrumentation team에 연락하세요.