> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# EventsElement

> 계정이 측정한 모든 이벤트 — 페이지 조회, 리드, 구매, 커스텀 픽셀 이벤트 — 를 필터링 가능한 원시 스트림으로 보여 줍니다. 모든 지표의 바탕이 되는 행들입니다: 핸들의 기간 동안 이벤트, 소스, 지역 또는 기기로 필터링하거나, 한 사람의 식별자를 검색해 전체 여정을 확인하세요. 사람 셀은 핸들에 `links.person`이 설정된 경우 해당 링크로 이동하고, 그렇지 않으면 `personOpened`로 전달됩니다.

> [!NOTE]
>
> 이 페이지는 `@whop/elements@1.10.0` 및 `@whop/elements-react@1.10.0`을 다룹니다.

*`v1.0.0`부터 지원.*

[`Tracking`](https://docs.whop.com/ko/elements/latest/tracking/overview) 안에 마운트됩니다. `accountId`와 `accessToken`은 여기에서 가져옵니다. props와 콜백은 생성 옵션 또는 React props로 전달합니다.

```tsx React theme={null}
import { WhopElements, Tracking, EventsElement } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Tracking /* options */>
        <EventsElement onPeriodChanged={(e) => console.log(e)} onAttributionModelChanged={(e) => console.log(e)} onFiltersChanged={(e) => console.log(e)} onPersonOpened={(e) => console.log(e)} />
      </Tracking>
    </WhopElements>
  );
}
```

```html JavaScript theme={null}
<script src="https://cdn.whop.com/elements/amber/elements.js" data-whop-elements></script>
<script type="module">
  const tracking = window.WhopElements().tracking.create({ /* options */ });
  tracking.create('events', {
    onPeriodChanged: (e) => console.log(e),
    onAttributionModelChanged: (e) => console.log(e),
    onFiltersChanged: (e) => console.log(e),
    onPersonOpened: (e) => console.log(e)
  }).mount('#tracking-events');
</script>
```

예시 데이터입니다. [Playground 열기](https://docs.whop.com/ko/elements/latest/tracking/overview#playground).

## Props

**from** `string`

기간을 핸들의 `period` 대신 정확한 ISO 8601 시점으로 고정합니다 — 딥 링크가 지표의 바탕이 되는 정확한 행을 재현하는 방법입니다. `from`과 `to`를 둘 다 설정하거나 둘 다 설정하지 마세요. 기본값은 `""`입니다.

**to** `string`

고정된 기간의 끝으로, ISO 8601 시점입니다. 기본값은 `""`입니다.

**source** `string`

트래픽 소스에 기여된 이벤트로 범위를 좁히며, 소스 경로로 지정합니다 — 계정의 캠페인 중 하나는 `whop:adcamp_…:*`, 그리고 `ext:*`, `referrer:*`, `direct`. 기본값은 `""`입니다.

**utmSource** `string`

트래픽에 포함된 `utm_source`로 범위를 좁힙니다. 기본값은 `""`입니다.

**country** `string`

`US` 또는 `GB` 같은 ISO 3166-1 alpha-2 국가 코드로 범위를 좁힙니다. 기본값은 `""`입니다.

**device** `string`

기기 유형으로 범위를 좁힙니다 — `desktop`, `mobile`, `tablet`, `bot`. 기본값은 `""`입니다.

**browser** `string`

브라우저 이름으로 범위를 좁힙니다. 기본값은 `""`입니다.

**os** `string`

운영 체제 이름으로 범위를 좁힙니다. 기본값은 `""`입니다.

**identifier** `string`

한 사람의 여정으로 범위를 좁힙니다 — 사람 ID, 이메일 또는 방문자 쿠키. 설정하면 목록은 기간을 무시하고 해당 사람의 전체 기록을 보여 줍니다. 검색 상자가 이 값을 변경합니다. 기본값은 `""`입니다.

**event** `string`

이벤트 이름으로 범위를 좁힙니다 — `payment.completed`, `pixel.lead`, `pixel.page`, 또는 커스텀 이벤트의 경우 `pixel.custom:<name>`. 광고 테이블의 결과 수가 링크할 때 사용하는 값과 같습니다. 기본값은 `""`입니다.

## 이벤트

생성 옵션 또는 React props로 콜백을 전달합니다.

### `onPeriodChanged`

보는 사람이 기간 선택기에서 기간을 변경했습니다. 같은 핸들 아래의 모든 화면은 이미 이를 따랐습니다. 이 값을 저장하고 핸들에 `period`/`customRange`로 다시 전달하세요. 그렇지 않으면 다음 마운트 시 기간이 초기화됩니다.

**payload** `object`

**속성**

**period** `string` *required*

`"today"`, `"yesterday"`, `"last_7_days"`, `"last_14_days"`, `"last_30_days"`, `"last_90_days"`, `"all_time"`, `"custom"` 중 하나입니다.

**customRange** `object | null` *required*

**속성**

**from** `string` *required*

**to** `string` *required*

### `onAttributionModelChanged`

보는 사람이 필터 행의 Attribution 메뉴에서 어떤 터치에 기여도를 부여할지 변경했습니다. 같은 핸들 아래의 모든 화면은 이미 기여도를 다시 계산했습니다. 이 값을 저장하고 핸들에 `attributionModel`로 다시 전달하세요. 그렇지 않으면 다음 마운트 시 원래대로 돌아갑니다.

**payload** `object`

**속성**

**attributionModel** `"last_touch" | "first_touch"` *required*

### `onFiltersChanged`

보는 사람이 필터 또는 식별자 검색을 변경했습니다. 무엇이 변경되었든 전체 필터 상태를 전달합니다 — 이를 자체 URL에 반영하고 props로 다시 전달하면 뷰를 재현할 수 있습니다.

**payload** `EventsFilterBag`

**속성**

**identifier** `string` *required*

**event** `string` *required*

**source** `string` *required*

**country** `string` *required*

**utmSource** `string` *required*

**device** `string` *required*

**browser** `string` *required*

**os** `string` *required*

**from** `string` *required*

**to** `string` *required*

### `onPersonOpened`

보는 사람이 사람 셀을 클릭했지만 핸들에 따라갈 `links.person`이 없습니다. 이를 사용해 `person` 엘리먼트를 표시하세요. 예: `createOverlay("person", { identifier: payload.personId })` (`personId`는 사람별로 안정적인 키이고, `identifier`는 해당 화면이 가진 것 중 사람이 가장 알아보기 쉬운 식별자입니다). 또는 핸들에 `links.person`을 전달해 셀을 실제 링크로 만드세요.

**payload** `object`

**속성**

**identifier** `string` *required*

**personId** `string` *required*

### `onLoaderStart`

로딩 스켈레톤이 처음 그려진 후, `onReady` 전에 실행됩니다.

### `onReady`

엘리먼트가 처음으로 완전히 그려진 후 실행됩니다.

### `onError`

엘리먼트가 로드에 실패하거나 충돌할 때 실행됩니다. 대체 화면은 계속 표시됩니다. 프로그래밍 방식으로 처리하려면 `code`를 사용하세요. `sourceKey`는 실패한 호스트 상태 소스를 식별합니다.

**e** `object`

**속성**

**message** `string` *required*

**code** `string`

**sourceKey** `string`

## 메서드

`create`가 반환한 핸들에서, 또는 React `ref`를 통해 호출합니다.

### `mount`

`target`에 엘리먼트를 마운트하고 로딩을 시작합니다. React 컴포넌트는 자동으로 마운트됩니다.

**매개변수**

**target** `string | HTMLElement` *required*

### `destroy`

엘리먼트를 제거하고 프레임과 구독을 해제합니다. 여러 번 호출해도 됩니다. React는 엘리먼트를 자동으로 제거합니다.

### `update`

마운트된 엘리먼트에 새 props를 병합합니다. React에서는 대신 컴포넌트 props를 변경하세요.

**매개변수**

**options** `Partial\<EventsElementProps\>` *required*

## 스타일링

이 엘리먼트는 스타일링용 클래스 이름을 노출하지 않습니다. 스타일을 변경하려면 `appearance`(테마, 강조 색상, 변수)를 사용하세요.


## Related topics

- [트래킹](https://docs.whop.com/ko/elements/latest/tracking/overview.md)
- [ChartElement](https://docs.whop.com/ko/elements/latest/ads/reporting-chart.md)
- [ChatElement(레거시)](https://docs.whop.com/ko/sdk/elements/chat-element.md)
