JavaScript SDK ⁠-⁠ SDK 초기화

설치

다음 명령을 실행하면 트래커와 함께 SDK가 설치되어 트래커의 모든 기능을 활용할 수 있습니다.

npm i @openreplay/tracker

초기화

OpenReplay 트래커를 인스턴스화할 때 여러 설정 옵션을 지정하여 녹화와 녹화 환경의 다양한 부분을 사용자 지정할 수 있습니다.

생성자에서 projectKey 옵션을 반드시 설정해야 합니다. 이 값은 OpenReplay 대시보드의 ‘Preferences > Projects’에서 확인할 수 있습니다.

싱글 페이지 애플리케이션(SPA)

웹사이트가 싱글 페이지 애플리케이션(SPA) 이라면 트래커를 싱글톤으로 사용할 수 있습니다:

import { tracker } from '@openreplay/tracker'

tracker.configure({
	projectKey: PROJECT_KEY,
  ingestPoint: "https://openreplay.mydomain.com/ingest", // when dealing with the self-hosted version of OpenReplay
})

tracker.start() // returns a promise with session info (sessionID, sessionHash, userUUID)

또는 새 클래스 인스턴스를 만들 수도 있습니다:

import OpenReplay from '@openreplay/tracker';
//...
const tracker = new OpenReplay({
  projectKey: PROJECT_KEY
});
tracker.start(); // returns a promise with session info (sessionID, sessionHash, userUUID)

서버 사이드 렌더링(SSR)

웹 앱이 서버 사이드 렌더링(SSR) 방식(예: NextJS, NuxtJS)이라면 아래 스니펫을 사용하세요. 앱이 시작된 후(useEffect 또는 componentDidMount 안에서) tracker.start()가 한 번 호출되도록 하세요.

import OpenReplay from '@openreplay/tracker/cjs';
//...
const tracker = new OpenReplay({
      projectKey: PROJECT_KEY,
      ingestPoint: "https://openreplay.mydomain.com/ingest", // when dealing with the self-hosted version of OpenReplay
});
//...
function MyApp() {
  useEffect(() => { // use componentDidMount in case of React Class Component
    tracker.start(); // returns a promise with session info (sessionID, sessionHash, userUUID)
  }, [])
}

예제

import OpenReplay from '@openreplay/tracker/cjs';
//...
const tracker = new OpenReplay({
      projectKey: PROJECT_KEY,
      ingestPoint: "https://openreplay.mydomain.com/ingest", // when dealing with the self-hosted version of OpenReplay
      capturePerformance: true,
      __DISABLE_SECURE_MODE: true // for local testing
});

초기화 옵션

생성자에 전달할 수 있는 옵션이 여러 가지 있으며, projectKey만 필수입니다.

일반

projectKey: string 추적할 프로젝트의 ID입니다.
sessionHash?: string 초기 세션의 해시입니다. 웹 앱에서 세션이 여러 서브도메인에 걸쳐 이어지지만 이를 하나의 녹화로 연결하고 싶을 때 유용합니다. 세션을 이어갈 수 없는 경우(세션이 존재하지 않거나 이미 종료된 경우) 트래커가 자동으로 새 세션을 시작합니다. 이 값은 stop()을 호출할 때도 반환됩니다. 자세한 내용은 여기를 참고하세요.
ingestPoint?: string 트래커가 이벤트를 전송할 OpenReplay 도메인(수집 지점)입니다. 예: https://openreplay.mydomain.com/ingest. OpenReplay Cloud 사용자는 생략할 수 있습니다. 기본값: https://api.openreplay.com/ingest(OpenReplay Cloud를 가리킵니다).
revID?: string 웹 앱의 리비전 ID입니다. 특정 릴리스 버전에서 발생하는 문제를 검색할 때 유용합니다.
resourceBaseHref?: string OpenReplay가 에셋(스타일, 글꼴, 아이콘)을 가져올 수 있는 공개 접근 가능 도메인을 가리킵니다. 이러한 에셋은 세션 리플레이를 제대로 재생하는 데 필요하므로, 사이트(및 에셋)가 비공개 도메인에 호스팅되어 있다는 제약을 우회할 때 유용한 옵션입니다. 예: https://mypublicsite.com/assets/.
captureIFrames?: boolean 웹 앱의 동일 도메인 iFrame을 모두 캡처합니다. 특정 iFrame만 추적하려면 대신 <iframe> 태그에 data-openreplay-capture HTML 속성을 추가하면 됩니다. 기본값: true.
disableClickmaps?: boolean CSS 선택자 계산(클릭맵에 사용)을 비활성화합니다. 기본값: false.
__debug__: number 디버그 로그를 활성화합니다. 기본값: 0(비활성화).
- 2: 오류.
- 3: 오류와 경고.
- 4: 오류, 경고, 로그.
- 5: 상세 출력.
autoResetOnWindowOpen?: boolean 이 옵션을 활성화하면 애플리케이션에서 새 탭을 열 때 sessionID가 초기화됩니다. 브라우저 탭 간에 세션 스토리지가 공유되어 sessionID가 중복되는 것을 방지하기 위해 window.open 메서드를 덮어씁니다. 기본값: false.
forceSingleTab: boolean 여러 탭에 걸쳐 이루어진 사용자 세션을 하나의 리플레이로 연결하는 멀티 탭 녹화 기능을 비활성화합니다. 이 옵션을 활성화하면 서로 다른 브라우저 탭에서 캡처된 세션이 각각 별도의 녹화로 기록됩니다. 기본값: false.
disableStringDict: boolean 녹화에서 문자열 딕셔너리 로직(스토리지 최적화용)을 비활성화합니다. 기본값: false.
fixedCanvasScaling: boolean 캔버스 이미지를 devicePixelRatio 대신 픽셀 밀도 1로 렌더링하도록 강제합니다(이미지 품질이 낮아질 수 있는 대신 최종 결과물의 크기가 작아집니다). 기본값: false.
disableCanvas?: boolean canvas 요소의 녹화를 비활성화합니다. 기본값: false.
assistSocketHost?: string Assist 플러그인 연결에 사용할 특정 호스트를 설정할 때 사용합니다. 기본값은 ingestPoint 값입니다.
analytics?: { active: boolean, ingestPoint?: string } Analytics SDK를 활성화하며, tracker.analytics(이벤트, 슈퍼 속성, 사용자 프로필)와 최상위 tracker.track() 단축 메서드를 사용할 수 있게 합니다. active가 true가 아니면 SDK는 인스턴스화되지 않으며, 그때까지 tracker.analytics는 null로 유지됩니다. ingestPoint를 사용하면 셀프 호스팅 배포에서 애널리틱스를 리플레이 수집 지점과 다른 엔드포인트로 전송할 수 있으며, OpenReplay Cloud에서는 무시됩니다. 기본값: { active: false }.
nodes?: { maintainer: MaintainerOptions } 새로 추가된 nodes.maintainer 옵션은 메모리를 관리하고 더 이상 사용되지 않는 DOM 노드를 정리하는 데 도움이 됩니다. 다음 매개변수가 있습니다:
- interval: number: 정리 작업 실행 사이의 시간 간격(밀리초)입니다. 기본값: 30 * 1000(30초).
- batchSize: number: 정리 작업을 실행할 때마다 검사하는 노드 수입니다. 기본값: 2500.
- enabled: boolean: 노드 메인테이너를 활성화하거나 비활성화합니다. 기본값: true.

스타일시트

inlineCss: number: 원격 스타일시트를 백엔드에 캐시하는 대신 일반 메시지로 기록하여 전송하도록 트래커에 강제합니다. CSS 파일이 비공개여서 OpenReplay 백엔드가 캐시할 수 없을 때 유용합니다. 가능한 값은 다음과 같습니다:
- 0: 백엔드가 CSS 파일을 캐시합니다. 기본 동작입니다.
- 1: 링크된 CSS 파일을 AdoptedStyleSheet 객체로 기록하려고 시도합니다.
- 2: 파일을 가져온 다음 리플레이를 위해 AdoptedStyleSheets 동작을 시뮬레이션합니다.
- 3: 파일을 가져온 다음 <style> 노드 안에 일반 CSS로 저장합니다. CSS 파일에 축약 속성(shorthand property)이 많은 경우 이 옵션을 사용하세요(CSSOM 사양 버그 대응).
css: CssRulesOptions: emotion-js 라이브러리로 빌드된 애플리케이션(예: MUI 컴포넌트)에 대한 지원을 개선합니다. 다음 매개변수가 있습니다:
- scanInMemoryCSS: boolean: emotionjs로 생성된 스타일에 문제가 있다면 이 옵션을 켜세요. 기본값: false.
- checkCssInterval: number: 규칙이 비어 있는 추적 대상 스타일시트를 얼마나 자주 스캔할지 지정합니다. 기본값: 200(ms).
- checkLimit: number: 변경(mutation) 횟수가 제한적이거나 초기 렌더링 이후 클라이언트에서 스타일시트가 하이드레이션되는 경우에 유용합니다. 각 스타일시트에 개별적으로 적용됩니다. 값은 X/checkCssInterval이어야 하며, X는 관찰 시간(ms)입니다. 기본값: 0(비활성화).

개인정보 보호

respectDoNotTrack?: boolean 사용자 브라우저에서 Do Not Track 플래그가 활성화되어 있으면 트래커를 시작하지 않습니다. 기본값: false.
obscureTextEmails?: boolean 텍스트 요소의 이메일을 가립니다. 이메일은 무작위 별표 문자열로 변환됩니다. 기본값: true.
obscureTextNumbers?: boolean 텍스트 요소의 숫자를 가립니다. 숫자는 무작위 별표 문자열로 변환됩니다. 기본값: false.
obscureInputEmails?: boolean 입력 필드의 이메일을 가립니다. 이메일 값은 무작위 별표 문자열로 변환됩니다. 기본값: true.
obscureInputNumbers?: boolean 입력 필드의 숫자를 가립니다. 숫자 값은 무작위 별표 문자열로 변환됩니다. 비활성화하는 경우 우편번호나 신용카드 정보처럼 민감한 데이터가 포함될 수 있는 입력 필드를 정제해야 합니다. 기본값: true.
obscureInputDates?: boolean 입력 필드의 날짜를 가립니다. 날짜 값은 무작위 별표 문자열로 변환됩니다. 기본값: false.
defaultInputMode?: 0 | 1 | 2 입력 값의 기본 캡처 모드입니다. 각각 일반(plain), 가림(obscured), 무시(ignored)를 의미합니다. 기본값: 2(무시).
urls: 다음 옵션을 통해 페이지 위치 이벤트가 기록되는 방식을 사용자 지정할 수 있습니다:
- urlSanitizer?: (url: string) => string 페이지 URL을 정제합니다(예: 사용 토큰 제거).
- titleSanitizer?: (title: string) => string 페이지 제목을 정제합니다.
resourceNameSanitizer?: (url: string) => string 기록되는 네트워크 리소스의 URL을 정제합니다.

제외된 데이터는 OpenReplay 서버로 전송되기 전에 가려지거나 제거된다는 점에 유의하세요. 위 옵션에 적용한 변경 사항은 소급 적용되지 않으며 새로 수집되는 데이터에만 적용됩니다. 자세한 내용은 데이터 정제를 참고하세요.

콘솔

consoleMethods?: Array<'log' | 'info' | 'warn' | 'error' 'debug' | 'assert'> | null 캡처할 콘솔 메서드 목록을 지정합니다. 기본값: ['log', 'info', 'warn', 'error', 'debug', 'assert']
consoleThrottling?: number 초당 캡처되는 콘솔 항목의 최대 개수입니다. 기본값: 30.

예외

captureExceptions?: boolean JavaScript 예외와 스택 트레이스를 캡처합니다. 기본값: true.

타이밍

captureResourceTimings?: boolean 리소스 타이밍을 기록합니다. 기본값: true.
capturePageLoadTimings?: boolean 페이지 로드 타이밍을 기록합니다. 기본값: true.
capturePageRenderTimings?: boolean Speed Index, Visually Complete, Time To Interactive 같은 페이지 렌더링 지표를 계산합니다. captureResourceTimings = true가 필요합니다. 기본값: true.

성능

capturePerformance?: boolean 프레임 레이트, CPU, 메모리 사용량 같은 성능 지표를 캡처합니다. 기본값: true.
longTasks?: boolean long-animation-frame 이벤트를 캡처합니다. 기본값: false.

네트워크

network 옵션은 fetch와 XHR의 네트워크 요청 및 페이로드 캡처와 관련된 옵션입니다.

network?: {
    failuresOnly: boolean;
    sessionTokenHeader: string;
    ignoreHeaders: Array<string> | boolean;
    capturePayload: boolean; // make sure you sanitize your data before enabling it
    sanitizer: (RequestResponseData) => RequestResponseData | null;
		captureInIframes: boolean;
  	axiosInstances: AxiosInstance[];
    useProxy?: boolean;
		tokenUrlMatcher?: (url: string) => boolean;
  }

민감한 데이터를 가리는 방법에 대한 예제와 자세한 내용은 네트워크 옵션을 참고하세요.

캔버스

canvas 옵션은 canvas/WebGL 요소의 캡처와 관련된 옵션입니다:

canvas?: {
  disableCanvas?: boolean
  fixedCanvasScaling?: boolean
  useAnimationFrame?: boolean
  fileExt?: 'webp' | 'png' | 'jpeg' | 'avif'
}

이 기능을 활성화하는 방법과 사용 가능한 옵션에 대한 자세한 내용은 캔버스와 WebGL을 참고하세요.

크로스 도메인 iFrame

crossdomain 옵션은 다른 도메인의 iFrame 캡처와 관련된 옵션입니다. captureIFrames 옵션과 함께 사용하며, 이 옵션은 반드시 true로 설정해야 합니다.

	crossdomain?: {
		/**
		 * Enable cross-domain tracking
		 * @default false
		 * */
		enabled?: boolean
		/**
		 * Used to specify the parent domain, will be '*' by default
		 * (Check your CSP settings)
		 * @default '*'
		 * */
		parentDomain?: string
	}

트래커 버전 14.0.10부터는 크로스 도메인 iFrame을 사용할 때 HTML 요소에 data-domain 속성이 더 이상 필요하지 않습니다.

다른 도메인의 iFrame을 캡처하는 방법에 대한 자세한 내용은 크로스 도메인 iFrame 추적을 참고하세요.

마우스 포인터

mouse 옵션은 클릭맵을 만들기 위해 클릭 시의 선택자를 캡처하는 것과 관련된 옵션입니다.

mouse?: 
  {
  disableClickmaps?: boolean
  minSelectorDepth?: number
  nthThreshold?: number
  maxOptimiseTries?: number
  }

disableClickmaps?: boolean 선택자 계산을 완전히 비활성화합니다. 기본값: false.
minSelectorDepth?: number 최적화된 선택자의 최소 길이입니다(기본값 2). 예: body > div > div > p => body > p
nthThreshold?: number nth-child 선택자로 대체하기 전에 선택자를 시도하는 횟수입니다. 이는 비용이 큰 작업이며 상당한 오버헤드가 발생할 수 있으므로 2000보다 높게 설정하지 마세요. 기본값: 1000.
maxOptimiseTries?: number 선택자를 최적화하고 줄이기 위해 시도하는 횟수입니다. 기본값: 10 000.

재연결

connAttemptCount?: number 트래커의 HTTP 요청이 백엔드에 도달하지 못할 때 재시도하는 최대 횟수입니다. 기본값: 10.
connAttemptGap?: number 재시도 사이의 간격입니다(ms 단위). 기본값: 8000.

보안

__DISABLE_SECURE_MODE?: boolean SSL이 없는 사이트에서 트래커와 백엔드 간의 비보안 연결을 허용합니다. 개발 목적으로만 사용해야 합니다. 기본값: false.

JavaScript SDK - SDK 초기화