> ## 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.

# 트래킹

> 계정이 추적하는 오디언스입니다. 픽셀이 확인한 모든 사람과 그들이 수행한 모든 이벤트를 다룹니다. `accountId`로 계정에 범위를 지정한 다음 `people`, `events` 또는 둘 다 마운트하세요. 둘은 같은 기간과 같은 기여 규칙을 읽으므로 나란히 놓인 두 화면이 서로 다른 내용을 보여 주는 일은 없습니다. `person`은 둘 중 어느 쪽에서든 클릭하면 이동하는 곳으로, 한 사람의 전체 기록을 보여 주며 인라인으로 마운트하거나 페이지 위에 표시할 수 있습니다. `links`는 사람 링크를 자체 페이지에 연결합니다.

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

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

## 플레이그라운드

예시 데이터로 엘리먼트를 조합해 보세요. 컨트롤을 조작하고, 엘리먼트를 추가 및 배치하고, 이벤트가 실시간으로 발생하는 것을 확인하세요.

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

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Tracking /* options */>
        {/* mount elements here */}
      </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 */ });
</script>
```

## 옵션

`whop.tracking.create({ … })`에 전달하거나, React에서는 `<Tracking>`의 props로 전달하세요.

**accountId** `string`

사람과 이벤트를 읽어 올 계정의 ID로, `biz_` 접두사가 붙습니다. 필수입니다. 기본값은 `""`입니다.

**accessToken** `string`

두 화면이 읽기에 사용하는 범위 지정 토큰입니다. 서버에서 `POST /api/v1/access_tokens`로 핸들 전체에 대해 하나의 토큰을 발급하고, 만료되기 전에 `update({ accessToken })`로 새 토큰을 설정하세요. 목록을 읽으려면 `member:basic:read` 또는 `company:basic:read`가 필요합니다. 필터 메뉴의 옵션 개수에는 추가로 `stats:read`가 사용되며, People 테이블의 저장된 오디언스 필터에는 `audience:basic:read`가 사용됩니다. 이러한 스코프가 없으면 메뉴에 표시되는 옵션이 줄어들 뿐입니다. 생략하면 호출에 뷰어 자신의 세션이 사용되며, 이는 동일 출처에서만 응답합니다.

**links** `CrossLinksConfig`

사람 링크가 연결될 사이트의 위치입니다. `person`은 두 개의 자리 표시자가 있는 절대 URL 템플릿이며, 각 자리 표시자는 행마다 URL 인코딩된 값으로 대체됩니다. `{personId}`는 안정적인 `prsn_…` ID로, 모든 화면에서 같은 사람에 대해 동일하므로 이를 기준으로 페이지를 구성하고 그곳에 `person` 엘리먼트를 마운트하세요. `{identifier}`는 화면이 가진 가장 사람이 알아보기 쉬운 식별자(알려진 경우 사용자 ID 또는 이메일)이므로 화면마다 다를 수 있습니다. 반드시 절대 URL(`https://…`)이어야 합니다. 상대 URL은 엘리먼트 프레임을 기준으로 해석되므로 설정되지 않은 것으로 처리됩니다. 설정하지 않으면 사람을 클릭할 때 대신 해당 엘리먼트에서 `personOpened`가 발생하며, 이는 페이지 위에 `person`을 표시하라는 신호입니다. `people` 및 `events` 기본 URL은 ads 핸들과의 대칭을 위해 허용되지만 이 핸들 아래의 어떤 엘리먼트도 이를 렌더링하지 않습니다. 기본값은 `{}`입니다.

**속성**

**people** `string`

**events** `string`

**person** `string`

**period** `string`

두 화면이 다루는 기간입니다: `today`, `yesterday`, `last_7_days`, `last_14_days`, `last_30_days`, `last_90_days`, `all_time` 또는 `custom`(`customRange`와 함께 사용). 엘리먼트에 선택기가 있으며 이 값을 변경합니다. `periodChanged`에서 다시 읽으세요. 기본값은 `"last_14_days"`입니다.

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

**customRange** `object | null`

`period`가 `custom`일 때 사용되는 명시적 기간으로, ISO 8601 시각으로 지정합니다. 그 외에는 무시됩니다. 기본값은 `null`입니다.

**속성**

**from** `string` *required*

**to** `string` *required*

**timezone** `"account" | "local"`

기간을 해석할 두 시간대 중 하나입니다: 계정 자체의 스케줄링 시간대인 `account`, 또는 뷰어의 브라우저 시간대인 `local`. 계정에 설정이 없으면 `account`는 뷰어의 시간대로 대체됩니다. 기본값은 `"account"`입니다.

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

소스별로 필터링할 때 사람의 여정에서 어떤 접점에 기여를 부여할지 지정합니다: 기본값인 `last_touch` 또는 `first_touch`. 엘리먼트에 선택기가 있으며 이 값을 변경하므로, 호스트는 이를 제어하고 `attributionModelChanged`에서 다시 읽을 수 있습니다. 기본값은 `"last_touch"`입니다.

**appearance** `Appearance`

이 그룹 엘리먼트의 시각적 사용자 지정입니다. 전역 `WhopElements({ appearance })`를 재정의합니다. `update({ appearance })`로 실시간으로 변경할 수 있습니다.

**locale** `WhopElementsLocale`

이 그룹 엘리먼트 UI 텍스트의 로케일입니다. 앱에 빌드된 로케일 중 하나로 설정하면 전역 구성을 재정의합니다. 그 외의 값은 기본 로케일로 대체됩니다.

## 이벤트

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

### `onLoadingChange`

그룹 로딩 상태가 바뀔 때 실행됩니다. 마운트된 엘리먼트 중 하나라도 로딩 중이면 값은 `true`입니다.

**loading** `boolean`

## 메서드

`whop.tracking.create({ … })` 또는 `useTracking()`으로 얻은 Tracking 핸들에서 호출하세요.

### `update`

마운트된 모든 엘리먼트에 새 핸들 옵션을 병합합니다. React에서는 대신 네임스페이스 props를 변경하세요.

**매개변수**

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

### `destroy`

이 핸들이 만든 모든 엘리먼트와 하위 컨트롤러를 파괴하고, 컨트롤러 프레임을 제거하고, 구독을 해제합니다. 여러 번 호출할 수 있지만, 파괴된 핸들은 다른 모든 호출을 거부합니다. 다시 시작하려면 새 핸들을 만드세요. React는 프로바이더가 언마운트될 때 그룹을 자동으로 제거합니다.

## 엘리먼트

이 그룹이 마운트하는 엘리먼트입니다. 각 엘리먼트에는 자체 페이지가 있습니다.

> [card] [PeopleElement](https://docs.whop.com/ko/elements/latest/tracking/people.md)
>
> 계정이 확인한 모든 사람입니다. 픽셀 활동으로 식별된 방문자와 고객을 소스, 지출액, 활동 카운터와 함께 보여 줍니다. 검색하고, 소스, 이벤트, 지역 또는 기기로 필터링하고, 아무 열이나 정렬하고, 페이지를 넘겨 보세요. 핸들에 `links.person`이 구성되어 있으면 행을 클릭할 때 해당 링크로 이동하고, 그렇지 않으면 `personOpened`로 전달됩니다.

> [card] [EventsElement](https://docs.whop.com/ko/elements/latest/tracking/events.md)
>
> 계정이 측정한 모든 이벤트(페이지 조회, 리드, 구매, 맞춤 픽셀 이벤트)를 필터링 가능한 원시 스트림으로 보여 줍니다. 모든 지표의 바탕이 되는 행입니다. 핸들의 기간에 걸쳐 이벤트, 소스, 지역 또는 기기로 필터링하거나, 한 사람의 식별자를 검색하여 전체 여정을 확인하세요. 핸들에 `links.person`이 구성되어 있으면 사람 셀을 클릭할 때 해당 링크로 이동하고, 그렇지 않으면 `personOpened`로 전달됩니다.

> [card] [PersonElement](https://docs.whop.com/ko/elements/latest/tracking/person.md)
>
> 계정이 한 사람에 대해 알고 있는 모든 것입니다. 누구인지, 어디에서 왔는지, 얼마를 지출했는지, 수행한 모든 이벤트를 순서대로 보여 줍니다. 사람을 클릭하면 이동하는 화면입니다. `links.person`이 가리키는 페이지에 마운트하거나, `people` 또는 `events`에서 `personOpened`가 발생하면 자체 페이지 위에 표시하세요. `identifier`는 사람이 확인된 적이 있는 모든 식별자를 받으므로 `personOpened` 페이로드를 그대로 여기서 조회할 수 있습니다.


## Related topics

- [Stats API 레퍼런스](https://docs.whop.com/ko/api-reference/stats/stats.md)
- [Whop API 개요](https://docs.whop.com/ko/api-reference/overview.md)
- [Whop CLI 명령](https://docs.whop.com/ko/cli/commands.md)
