> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickStack용 브라우저 SDK - ClickHouse 관측성 스택

# 브라우저 JS

export const ClickStackIntegrates = ({signals = []}) => {
  const list = Array.isArray(signals) ? signals : String(signals).split(",");
  const supported = list.map(s => String(s).trim().toLowerCase());
  const pillStyle = {
    display: "inline-flex",
    alignItems: "center",
    padding: "0.125rem 0.625rem",
    borderRadius: "9999px",
    fontSize: "0.8125rem",
    fontWeight: 500,
    lineHeight: 1.6,
    color: "#161517",
    backgroundColor: "#faff69",
    border: "1px solid rgba(0, 0, 0, .1)",
    marginRight: "0.5rem"
  };
  return <div style={{
    margin: "0 0 1.25rem"
  }}>
      <span style={{
    marginRight: "0.5rem"
  }}>이 가이드에서 통합하는 항목:</span>
      {supported.includes("logs") && <span style={pillStyle}>로그</span>}
      {supported.includes("metrics") && <span style={pillStyle}>메트릭</span>}
      {supported.includes("traces") && <span style={pillStyle}>트레이스</span>}
    </div>;
};

ClickStack 브라우저 SDK를 사용하면 프론트엔드 애플리케이션을 계측해
이벤트를 ClickStack으로 전송할 수 있습니다. 이를 통해 네트워크
요청과 예외를 백엔드 이벤트와 함께 단일 타임라인에서 확인할 수 있습니다.

또한 세션 리플레이 데이터를 자동으로 캡처하고 연관시키므로,
애플리케이션을 사용하는 동안 사용자가 보고 있던 내용을 시각적으로
단계별로 따라가며 디버깅할 수 있습니다.

<ClickStackIntegrates signals={['logs', 'traces']} />

<h2 id="getting-started">
  시작하기
</h2>

<br />

<Tabs>
  <Tab title="패키지 import">
    **패키지 import로 설치(권장)**

    다음 명령으로 [브라우저 패키지](https://www.npmjs.com/package/@hyperdx/browser)를 설치합니다.

    ```shell theme={null}
    npm install @hyperdx/browser
    ```

    **ClickStack 초기화**

    ```javascript theme={null}
    import HyperDX from '@hyperdx/browser';

    HyperDX.init({
        url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
        apiKey: '<YOUR_INGESTION_API_KEY>', // Managed ClickStack에서는 생략
        service: 'my-frontend-app',
        tracePropagationTargets: [/api.myapp.domain/i], // 프론트엔드 요청과 백엔드 요청의 trace를 연결하도록 설정
        consoleCapture: true, // 콘솔 로그 수집(기본값: false)
        advancedNetworkCapture: true, // HTTP 요청/응답의 전체 header와 본문 수집(기본값: false)
    });
    ```
  </Tab>

  <Tab title="스크립트 태그">
    **스크립트 태그로 설치(대안)**

    NPM으로 설치하는 대신 스크립트 태그로 스크립트를 포함해 사용할 수도
    있습니다. 이렇게 하면 전역 변수 `HyperDX`가 제공되며, NPM 패키지와 동일한
    방식으로 사용할 수 있습니다.

    현재 사이트를 번들러로 빌드하지 않는 경우 이 방법을 권장합니다.

    ```html theme={null}
    <script src="//www.unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
    <script>
      window.HyperDX.init({
        url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
        apiKey: '<YOUR_INGESTION_API_KEY>', // Managed ClickStack에서는 생략
        service: 'my-frontend-app',
        tracePropagationTargets: [/api.myapp.domain/i], // 프론트엔드 요청과 백엔드 요청의 trace를 연결하도록 설정
      });
    </script>
    ```
  </Tab>
</Tabs>

<h3 id="options">
  옵션
</h3>

* `apiKey` - ClickStack 수집 API Key입니다.
* `service` - HyperDX UI에 이벤트가 표시될 서비스 이름입니다.
* `tracePropagationTargets` - 프론트엔드와 백엔드 trace를 연결하기 위해 HTTP
  요청과 대조할 regex 패턴 목록입니다. 패턴 중 하나와 일치하는 모든 요청에
  추가 `traceparent` header를 추가합니다. 백엔드 API 도메인(예:
  `api.yoursite.com`)으로 설정해야 합니다.
* `consoleCapture` - (선택 사항) 모든 콘솔 로그를 수집합니다(기본값 `false`).
* `advancedNetworkCapture` - (선택 사항) 전체 요청/응답 headers
  및 본문을 수집합니다(기본값 `false`).
* `url` - (선택 사항) OpenTelemetry collector URL이며,
  자체 호스팅 인스턴스에서만 필요합니다.
* `maskAllInputs` - (선택 사항) 세션 리플레이에서 모든 입력 필드를
  마스킹할지 여부입니다(기본값 `false`).
* `maskAllText` - (선택 사항) 세션 리플레이에서 모든 텍스트를 마스킹할지 여부입니다(기본값
  `false`).
* `disableIntercom` - (선택 사항) Intercom 통합을 비활성화할지 여부입니다(기본값 `false`)
* `disableReplay` - (선택 사항) 세션 리플레이를 비활성화할지 여부입니다(기본값 `false`)

<h2 id="additional-configuration">
  추가 구성
</h2>

<h3 id="attach-user-information-or-metadata">
  사용자 정보 또는 메타데이터 추가
</h3>

사용자 정보를 추가하면 HyperDX UI에서 세션과 이벤트를 검색하거나 필터링할 수
있습니다. 이는 클라이언트 세션 중 언제든지 호출할 수 있습니다. 현재
클라이언트 세션과 이 호출 이후에 전송되는 모든 이벤트는 사용자 정보와 연결
됩니다.

`userEmail`, `userName`, `teamName`은 세션 UI에 해당 값을 표시하는 데
사용되지만 생략할 수도 있습니다. 그 외의 추가 값도 지정할 수 있으며,
이벤트를 검색하는 데 사용할 수 있습니다.

```javascript theme={null}
HyperDX.setGlobalAttributes({
  userId: user.id,
  userEmail: user.email,
  userName: user.name,
  teamName: user.team.name,
  // 기타 사용자 정의 속성...
});
```

<h3 id="auto-capture-react-error-boundary-errors">
  React error boundary 오류 자동 수집
</h3>

React를 사용하는 경우, 에러 바운더리(error boundary) 컴포넌트를
`attachToReactErrorBoundary` 함수에 전달하면 React error boundary 내에서 발생하는
오류를 자동으로 수집할 수 있습니다.

```javascript theme={null}
// ErrorBoundary를 가져옵니다 (예시로 react-error-boundary를 사용합니다)
import { ErrorBoundary } from 'react-error-boundary';

// ErrorBoundary 컴포넌트에 연결하여 해당 컴포넌트의 모든 인스턴스에서 발생하는
// 오류를 캡처합니다.
HyperDX.attachToReactErrorBoundary(ErrorBoundary);
```

<h3 id="send-custom-actions">
  사용자 지정 액션 보내기
</h3>

특정 애플리케이션 이벤트(예: 회원 가입, 제출 등)를 명시적으로 추적하려면 이벤트 이름과 선택적 메타데이터를 함께 지정해 `addAction` 함수를 호출할 수 있습니다.

예시:

```javascript theme={null}
HyperDX.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});
```

<h3 id="enable-network-capture-dynamically">
  네트워크 캡처 동적으로 활성화하기
</h3>

네트워크 캡처를 동적으로 활성화하거나 비활성화하려면 필요에 따라 `enableAdvancedNetworkCapture` 또는 `disableAdvancedNetworkCapture` 함수를 호출하면 됩니다.

```javascript theme={null}
HyperDX.enableAdvancedNetworkCapture();
```

<h3 id="enable-resource-timing-for-cors-requests">
  CORS 요청에 대한 리소스 타이밍 활성화
</h3>

프런트엔드 애플리케이션이 다른 도메인으로 API 요청을 보내는 경우,
선택적으로 `Timing-Allow-Origin`[헤더](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Timing-Allow-Origin)가 요청과 함께 전송되도록 설정할 수
있습니다. 이렇게 하면 ClickStack이 [`PerformanceResourceTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming)을 통해 DNS 조회, 응답
다운로드 등 요청에 대한 세부적인 리소스 타이밍 정보를 수집할 수 있습니다.

`cors` 패키지와 함께 `express`를 사용 중이라면, 다음
스니펫을 사용하여 헤더를 활성화할 수 있습니다:

```javascript theme={null}
var cors = require('cors');
var onHeaders = require('on-headers');

// ... 나머지 코드

app.use(function (req, res, next) {
  onHeaders(res, function () {
    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
    if (allowOrigin) {
      res.setHeader('Timing-Allow-Origin', allowOrigin);
    }
  });
  next();
});
app.use(cors());
```