> ## 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`로 Whop 계정에 범위를 지정하세요. 그 아래의 광고 계정은 서버 측에서 할당되며 여기에 노출되지 않습니다. 그런 다음 계정의 지출과 성과를 보려면 `reporting`을, 캠페인을 빌드하려면 `campaign-creator`를, 시작에 필요한 Whop Ads 계약에 서명하려면 `ads-agreement`를 마운트하세요.

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

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

## 플레이그라운드

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

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

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

## 옵션

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

**accountId** `string`

광고 정보를 읽을 `biz_` 접두사가 붙은 Whop 계정 ID입니다. 필수이며, 광고 계정 ID가 아닙니다. 기본값은 `""`입니다.

**accessToken** `string`

이 핸들 아래의 모든 화면이 읽고 쓸 때 사용하는 범위 지정 토큰입니다. **엘리먼트마다 하나가 아니라 핸들 전체에 대해 하나의 토큰을 발급하세요.** 마운트할 모든 엘리먼트의 스코프를 파악하고, 하나의 토큰에 이를 요청한 뒤 여기에 설정하세요. 핸들은 그 하나의 자격 증명을 각 엘리먼트의 프레임에 전달하므로, 화면마다 두 번째 토큰을 쓰면 얻는 것 없이 추적할 만료일만 여러 개로 늘어납니다. 서버에서 `POST /api/v1/access_tokens`로 발급하고, 만료되기 전에 `update({ accessToken })`로 새 토큰을 설정하세요. 모든 것을 마운트하려면 `ad_campaign:read`/`:create`, `ad_group:read`, `ad:read`, `stats:read`, 테이블의 행 작업에 사용되는 `:update`/`:delete` 스코프, `campaign-creator`가 실행하는 픽셀 검사를 위한 `company:basic:read`, 광고비 카드를 추가하기 위한 `payment:charge` 및 `user:email:read`가 필요합니다. 청구 슬롯은 `member:payment_methods:read`로 저장된 카드와 사용 가능한 지갑을 나열합니다. 더 적은 화면을 마운트하면 더 적은 스코프를 요청할 수 있지만, 여전히 하나의 토큰을 사용합니다. 생략하면 호출에 뷰어 자신의 세션이 사용되며, 이는 동일 출처에서만 응답합니다.

**links** `CrossLinksConfig`

보고서 `table`의 클릭 수와 결과 수가 연결될 사이트의 위치입니다. 일반적으로 `tracking` 네임스페이스의 `people` 및 `events` 엘리먼트를 마운트한 페이지입니다. `people`과 `events`는 절대 기본 URL(`https://…`)이며, 테이블은 해당 엘리먼트가 props로 받는 것과 같은 쿼리 매개변수(`?source=whop:adcamp_…:*&event=…&from=…&to=…`)를 덧붙이므로 대상 페이지는 URL에서 바로 엘리먼트를 하이드레이트할 수 있습니다. 상대 URL은 엘리먼트 프레임을 기준으로 해석되므로 설정되지 않은 것으로 처리되며, 설정되지 않은 링크는 수치를 일반 숫자로 렌더링합니다. 기본값은 `{}`입니다.

**properties**

**people** `string`

**events** `string`

**person** `string`

**appearance** `Appearance`

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

**locale** `WhopElementsLocale`

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

## 이벤트

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

### `onBillingChanged`

계정의 광고비 결제 수단이 변경되었고 변경 사항이 저장되었습니다. 슬롯 값은 수단 ID 자체입니다. 카드는 `payt_…`, 잔액은 `ldgr_…`이며, `backup`이 비어 있으면 설정된 것이 없다는 뜻입니다.

**payload** `object`

**properties**

**primary** `string` *required*

**backup** `string` *required*

### `onLoadingChange`

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

**loading** `boolean`

## 메서드

`whop.ads.create({ … })` 또는 `useAds()`로 얻은 Ads 핸들에서 호출하세요.

### `update`

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

**매개변수**

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

### `destroy`

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

## 엘리먼트

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

> [card] [보고서](https://docs.whop.com/ko/elements/latest/ads/reporting)
>
> 광고 계정의 보고서입니다. 특정 기간 동안 지출한 금액과 그 성과를 원하는 수준으로 좁혀 보여 줍니다. `chart`, `table` 또는 둘 다 마운트하세요. 둘은 같은 기간, 같은 기여 규칙, 같은 선택 항목을 읽으므로 나란히 놓인 두 화면이 서로 다른 내용을 보여 주는 일은 없습니다. `ads` 핸들의 `links` 구성은 테이블의 클릭 수와 결과 수를 `tracking` 네임스페이스의 `people` 및 `events`를 마운트한 자체 페이지에 연결합니다. *(하위 컨트롤러, 엘리먼트 3개)*

> [card] [BillingSetupElement](https://docs.whop.com/ko/elements/latest/ads/billing-setup.md)
>
> 광고비가 청구될 결제 수단을 지정합니다. 먼저 사용되는 기본 수단과, 기본 수단이 실패할 때 사용되는 선택적 백업 수단입니다. 둘 다 계정에 이미 저장된 수단 중에서 선택하며, 하나를 고르면 즉시 저장되므로 별도의 제출 단계가 없습니다. 카드를 추가하면 페이지 위에 카드 양식이 열리고, 완료 후 이를 요청한 슬롯으로 돌아갑니다. 계정에 잔액이 있으면 카드와 함께 계정 자체 잔액도 표시됩니다.

> [card] [CampaignCreatorElement](https://docs.whop.com/ko/elements/latest/ads/campaign-creator.md)
>
> 광고 캠페인 빌더입니다. 목표와 예산, 타겟팅과 일정이 포함된 광고 그룹, 크리에이티브가 포함된 광고 자체까지 시작에 이르는 전체 흐름을 다룹니다. 새 캠페인을 만들 때는 빈 상태로 열리고, `campaignId`를 전달하면 기존 캠페인으로 열립니다. 픽셀 검사기도 실행합니다. 광고 그룹의 전환 이벤트가 대상 URL에서 활성화되어 있어야 시작할 수 있으며, 누락된 설치를 수정할 수 있도록 이 엘리먼트 안에서 `pixel-setup` 마법사가 열립니다. 또한 계정이 Whop Ads 계약에 서명해야 시작할 수 있습니다. 서명하지 않은 경우 핸들이 빌더 위에 `ads-agreement`를 열고, 서명이 완료되면 시작이 계속 진행됩니다. 예산은 계정의 `ads_reporting_currency`(보고서에서 이미 사용하는 통화)로 입력 및 표시되며, 현재 환율에 따라 USD로 환산되어 청구됩니다. `ads` 핸들에 설정하는 하나의 토큰에는 엘리먼트마다 별도의 토큰을 사용하는 대신 캠페인 스코프와 함께 픽셀 스코프(`ad_campaign:create` 및 `company:basic:read`)가 포함되어야 합니다.

> [card] [AdsAgreementElement](https://docs.whop.com/ko/elements/latest/ads/ads-agreement.md)
>
> 계정의 Whop Ads 서비스 및 결제 승인 계약에 서명합니다. 계정의 광고비 청구 정보를 저장하면 계약이 열리며, 권한 있는 대표자가 서명하기 전까지는 어떤 캠페인도 시작할 수 없습니다. 서명자는 전체 법적 이름과 선택적으로 직함을 입력하고 약관에 동의하며, 입력된 서명은 계약과 함께 보관됩니다. 서명이 완료되면 누가 언제 서명했는지 표시하고, 청구가 설정되기 전에는 서명할 것이 없다고 표시합니다. `campaign-creator`는 시작에 서명이 필요할 때 빌더 위에 이 엘리먼트를 자동으로 열므로, 설정 페이지나 온보딩 페이지처럼 미리 서명을 받으려는 경우에만 직접 마운트하세요.


## Related topics

- [Whop Ads로 광고하기](https://docs.whop.com/ko/developer/ads/overview.md)
- [Whop API 개요](https://docs.whop.com/ko/api-reference/overview.md)
- [Financial Activity API](https://docs.whop.com/ko/api-reference/ledgers/ledger-activity.md)
