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

# 보고서

> 광고 계정의 보고서입니다. 특정 기간 동안 지출한 금액과 그 성과를 원하는 수준으로 좁혀 보여 줍니다. `chart`, `table` 또는 둘 다 마운트하세요. 둘은 같은 기간, 같은 기여 규칙, 같은 선택 항목을 읽으므로 나란히 놓인 두 화면이 서로 다른 내용을 보여 주는 일은 없습니다. `ads` 핸들의 `links` 구성은 테이블의 클릭 수와 결과 수를 `tracking` 네임스페이스의 `people` 및 `events`를 마운트한 자체 페이지에 연결합니다.

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

*`v1.0.0`부터 사용 가능.*

[`Ads`](https://docs.whop.com/ko/elements/latest/ads/overview) 안에 마운트됩니다. 생성해 핸들을 얻은 다음, 그 핸들에 엘리먼트를 마운트하세요. 하위 컨트롤러를 제거하려면 `destroy()`를 호출하세요. 새 핸들을 얻으려면 다시 생성하세요.

## 미리보기

예시 데이터로 이 하위 컨트롤러의 기본 배치를 보여 주는 실시간 인터랙티브 데모입니다.

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

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Ads /* options */>
        <Reporting>
          <ChartElement />
          <TableElement />
        </Reporting>
      </Ads>
    </WhopElements>
  );
}
```

```html JavaScript theme={null}
<script src="https://cdn.whop.com/elements/amber/elements.js" data-whop-elements></script>
<script type="module">
  const ads = window.WhopElements().ads.create({ /* options */ });
  const reporting = ads.create('reporting', { /* options */ });
  reporting.create('chart').mount('#ads-reporting-chart');
  reporting.create('table').mount('#ads-reporting-table');
</script>
```

## 옵션

`ads.create('reporting', { … })`에 전달하거나, React에서는 `<Reporting>`의 props로 전달하세요. 상위에서 주입되는 props는 여기에 표시되지 않습니다.

**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`입니다.

**properties**

**from** `string` *required*

**to** `string` *required*

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

모든 보고 수치에 적용할 시간대 선택입니다. 계정의 `preferences.ads_scheduling_timezone`을 사용하려면 `account`를, 뷰어의 브라우저 시간대를 사용하려면 `local`을 지정하세요. 차트가 제공하는 선택지는 이 두 가지뿐입니다. 자유 형식의 IANA 시간대는 선택기가 데이터에 잘못된 레이블을 붙이게 할 수 있으며, 뷰어가 선택을 바꾸면 사라집니다. 다른 시간대로 보고하려면 계정 설정을 변경하세요. 계정에 설정이 없으면 `account`는 뷰어의 시간대로 대체됩니다. 기본값은 `"account"`입니다.

**currency** `string`

환산 금액에 사용할 소문자 세 글자 ISO 4217 통화 코드입니다(예: `usd` 또는 `eur`). 설정하지 않으면 계정의 `preferences.ads_reporting_currency`가 사용됩니다. 기본값은 `""`입니다.

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

구매자 여정에서 어떤 접점에 기여를 부여할지 지정합니다: 기본값인 `last_touch` 또는 `first_touch`. 두 경우 모두 여정 어디에서든 Whop 접점이 있으면 Whop 버킷에 기여가 부여되며, 모델은 양 끝점만 선택합니다. 테이블에 선택기가 있으며 이 값을 변경하므로, 호스트는 이를 제어하고 `attributionModelChanged`에서 다시 읽을 수 있습니다. 기본값은 `"last_touch"`입니다.

**campaignIds** `string[]`

보고 대상을 이 광고 캠페인(`adcamp_…`)으로 좁힙니다. 비어 있으면 전체 계정을 보고합니다. `adGroupIds` 또는 `adIds`가 설정되면 이를 재정의합니다. **정확한 수치를 얻으려면 ID를 하나만 전달하세요.** 보고 API는 단일 소스 경로로 범위를 지정하므로, 둘 이상이 주어지면 차트는 첫 번째 것만 보고합니다. 기본값은 `[]`입니다.

**adGroupIds** `string[]`

보고 대상을 이 광고 그룹(`adgrp_…`)으로 좁힙니다. `campaignIds`보다 우선합니다. 단일 ID 주의 사항이 동일하게 적용됩니다. 기본값은 `[]`입니다.

**adIds** `string[]`

보고 대상을 이 광고(`ad_…`)로 좁힙니다. 가장 좁은 필터로, 다른 두 필터보다 우선합니다. 단일 ID 주의 사항이 동일하게 적용됩니다. 기본값은 `[]`입니다.

**tab** `"ads" | "all" | "businesses" | "campaigns" | "ad-groups"`

`table` 엘리먼트가 처음 열 테이블입니다: `campaigns`, `ad-groups`, `ads` 또는 트래픽 소스 보기를 위한 `all`. `all`은 소스 시리즈가 계정 수준에만 존재하므로 항상 계정 전체를 보고합니다. 따라서 함께 설정한 필터는 테이블은 좁히지만 차트는 좁히지 않습니다. 기본값은 `"campaigns"`입니다.

**sources** `string[] | null`

차트가 보고할 트래픽을 소스 경로로 지정합니다. Whop을 통해 구매한 광고는 `whop:*`, 다른 곳에서 운영한 광고는 `ext:*` 및 `ext:<platform>:*`, 오가닉은 `referrer:*`, 그리고 `direct`, `other`가 있습니다. 기본값인 `null`은 Whop 광고만 보고하고, `[]`는 모든 소스를 보고하며, 비어 있지 않은 배열은 해당 소스를 보고합니다. Whop 광고 내에서 범위를 좁히는 `campaignIds` 등과는 다른 축입니다. 지출은 Whop 광고 구매에만 사용되므로, 이 값이 무엇이든 지출 기반 비율은 Whop에 귀속된 상태로 유지됩니다. `table` 엘리먼트의 All 탭이 이 값을 변경합니다. 기본값은 `null`입니다.

## 이벤트

콜백은 create 옵션 또는 React props로 전달하세요.

### `onEditRequested`

뷰어가 행 메뉴, 초안 행 또는 세부 정보 오버레이의 Edit ad에서 무언가를 편집하려고 요청했습니다. `campaignId`는 항상 포함되며, `adGroupId`와 `adId`는 클릭한 대상으로 범위를 좁힙니다. `useCampaignCreator`가 꺼져 있을 때만 발생합니다. 켜져 있으면 대신 페이지 위에 빌더가 열리고 이 이벤트는 발생하지 않습니다.

**payload** `AdsEditTarget`

**properties**

**campaignId** `string` *required*

**adGroupId** `string`

**adId** `string`

## 메서드

`ads.create('reporting', { … })`로 얻은 하위 핸들에서 호출하세요.

### `update`

하위 컨트롤러에 새 props와 콜백을 병합합니다.

**매개변수**

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

### `destroy`

하위 컨트롤러와 그 엘리먼트를 파괴한 다음 전용 슬롯을 해제합니다. 이후의 `create("reporting")`은 새로 시작합니다.

## 엘리먼트

이 하위 컨트롤러가 마운트하는 엘리먼트입니다. 각 엘리먼트에는 자체 페이지가 있습니다.

> [card] [ChartElement](https://docs.whop.com/ko/elements/latest/ads/reporting-chart.md)
>
> 특정 기간 동안의 계정 성과를 보여 주며, 지출, 노출, 클릭 또는 계정이 기록하는 모든 전환 중 무엇을 표시할지 고르는 선택기가 있습니다. 읽기 전용입니다.

> [card] [TableElement](https://docs.whop.com/ko/elements/latest/ads/reporting-table.md)
>
> 광고 계정의 캠페인, 광고 그룹, 광고를 하나의 테이블에 보여 주며, 그 사이를 이동하는 탭이 있습니다. 행을 선택해 하위 수준을 좁히고, 검색하고, 정렬하고, 수치를 세분화하고, 열을 선택하고, 행에서 바로 일시 중지, 재개, 복제 또는 삭제할 수 있습니다. 보고 기간과 필터링된 행은 핸들에 저장되므로, 옆에 마운트한 차트는 정확히 같은 대상을 보고합니다.


## Related topics

- [보고서](https://docs.whop.com/ko/elements/latest/wallet/reports.md)
- [BalanceReportElement](https://docs.whop.com/ko/elements/latest/wallet/reports-balanceReport.md)
- [ReportActivityElement](https://docs.whop.com/ko/elements/latest/wallet/reports-reportActivity.md)
