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

# Ads

> Una cuenta publicitaria. Vincúlala a una cuenta de Whop con `accountId` (la cuenta publicitaria subyacente se asigna en el servidor y nunca aparece aquí) y después monta `reporting` para ver lo que la cuenta gastó y lo que obtuvo, `campaign-creator` para crear una campaña o `ads-agreement` para firmar el acuerdo de Whop Ads que requiere un lanzamiento.

> [!NOTE]
>
> Esta página documenta `@whop/elements@1.10.0` y `@whop/elements-react@1.10.0`.

*Desde `v1.0.0`.*

## Playground

Combina los elementos con datos de ejemplo. Usa los controles, añade y organiza elementos, y observa cómo se disparan los eventos en vivo:

```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>
```

## Opciones

Pásalas a `whop.ads.create({ … })`, o como props de `<Ads>` en React.

**accountId** `string`

ID de la cuenta de Whop, con el prefijo `biz_`, cuya publicidad se lee. Obligatorio; no es un ID de cuenta publicitaria. Por defecto es `""`.

**accessToken** `string`

Un token con alcance limitado con el que leen y escriben todas las superficies de este handle. **Genera un solo token para todo el handle, no uno por elemento.** Determina los scopes de todos los elementos que vas a montar, solicítalos en un único token y establécelo aquí: el handle proyecta esa única credencial en el frame de cada elemento, así que un segundo token por superficie no aporta nada y te deja varias fechas de caducidad que controlar en lugar de una. Genéralo en tu servidor con `POST /api/v1/access_tokens` y establece uno nuevo con `update({ accessToken })` antes de que caduque. Montarlo todo necesita `ad_campaign:read`/`:create`, `ad_group:read`, `ad:read`, `stats:read`, los scopes `:update`/`:delete` que usan las acciones de fila de la tabla, `company:basic:read` para las comprobaciones del píxel que ejecuta `campaign-creator`, y `payment:charge` más `user:email:read` para añadir una tarjeta de gasto publicitario; las ranuras de facturación enumeran las tarjetas guardadas y las billeteras con saldo disponible con `member:payment_methods:read`. Montar menos superficies puede requerir menos scopes, siempre en el mismo token. Si se omite, las llamadas usan la propia sesión del visitante, que solo responde en el mismo origen.

**links** `CrossLinksConfig`

A dónde enlazan en tu sitio los recuentos de clics y resultados de la `table` de informes; normalmente, las páginas en las que montaste los elementos `people` y `events` del namespace `tracking`. `people` y `events` son URL base absolutas (`https://…`); la tabla añade los mismos parámetros de consulta que esos elementos aceptan como props (`?source=whop:adcamp_…:*&event=…&from=…&to=…`), para que la página de destino pueda hidratar su elemento directamente desde su URL. Una URL relativa se resolvería contra el frame del elemento, así que se trata como no establecida; los enlaces no establecidos muestran los recuentos como cifras simples. Por defecto es `{}`.

**propiedades**

**people** `string`

**events** `string`

**person** `string`

**appearance** `Appearance`

Personalización visual para los elementos de este grupo. Anula el `WhopElements({ appearance })` global. Cámbiala en vivo con `update({ appearance })`.

**locale** `WhopElementsLocale`

Configuración regional para el texto de la interfaz de los elementos de este grupo. Establécela en una de las configuraciones regionales incluidas en la app para anular la configuración global. Cualquier otro valor recurre a la configuración regional predeterminada.

## Eventos

Pasa los callbacks en las opciones de creación o como props de React.

### `onBillingChanged`

Los métodos de pago del gasto publicitario de la cuenta cambiaron y el cambio se guardó. Los valores de las ranuras son los propios ID de los métodos: `payt_…` para una tarjeta, `ldgr_…` para un saldo; un `backup` vacío significa que no hay ninguno establecido.

**payload** `object`

**propiedades**

**primary** `string` *required*

**backup** `string` *required*

### `onLoadingChange`

Se ejecuta cuando cambia el estado de carga agrupado. El valor es `true` mientras algún elemento montado todavía se está cargando.

**loading** `boolean`

## Métodos

Llámalos en el handle de Ads obtenido de `whop.ads.create({ … })` o `useAds()`.

### `update`

Combina nuevas opciones del handle en todos los elementos montados. En React, cambia las props del namespace en su lugar.

**Parámetros**

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

### `destroy`

Destruye todos los elementos y subcontroladores que creó este handle, elimina el frame del controlador y libera sus suscripciones. Puedes llamarlo más de una vez, pero un handle destruido rechaza cualquier otra llamada: crea un nuevo handle para empezar de nuevo. React elimina el grupo automáticamente cuando el provider se desmonta.

## Elementos

Los elementos que monta este grupo. Cada uno tiene su propia página:

> [card] [Informes](https://docs.whop.com/es/elements/latest/ads/reporting)
>
> Los informes de una cuenta publicitaria: lo que gastó y lo que obtuvo, en un periodo, al nivel al que lo acotes. Monta `chart`, `table` o ambos: leen el mismo periodo, la misma regla de atribución y la misma selección, así que dos superficies una al lado de la otra nunca pueden discrepar sobre lo que muestran. La configuración `links` del handle `ads` conecta los recuentos de clics y resultados de la tabla con tus propias páginas, aquellas en las que montaste `people` y `events` del namespace `tracking`. *(subcontrolador, 3 elementos)*

> [card] [BillingSetupElement](https://docs.whop.com/es/elements/latest/ads/billing-setup.md)
>
> Los métodos de pago con los que se factura el gasto publicitario: uno principal que se usa primero y uno de respaldo opcional para cuando falla. Ambos se eligen entre los métodos ya guardados en la cuenta, y al elegir uno se guarda de inmediato: no hay un envío aparte. Añadir una tarjeta abre un formulario de tarjeta sobre tu página y vuelve a la ranura que lo solicitó. El saldo propio de la cuenta aparece junto a sus tarjetas siempre que la cuenta tenga uno.

> [card] [CampaignCreatorElement](https://docs.whop.com/es/elements/latest/ads/campaign-creator.md)
>
> El creador de campañas publicitarias: objetivo y presupuesto, grupos de anuncios con su segmentación y su programación, y los propios anuncios con sus creatividades; todo el flujo hasta el lanzamiento. Se abre vacío para crear una nueva campaña, o sobre una existente cuando pasas `campaignId`. También ejecuta el comprobador del píxel: un lanzamiento requiere que el evento de conversión del grupo de anuncios esté activo en la URL de destino, y el asistente `pixel-setup` se abre dentro de este elemento para corregir una instalación que falta. Un lanzamiento también requiere que la cuenta haya firmado el acuerdo de Whop Ads: si no lo ha hecho, el handle abre `ads-agreement` sobre el creador y el lanzamiento continúa una vez firmado. Los presupuestos se introducen y se muestran en la `ads_reporting_currency` de la cuenta (la moneda que ya usan sus informes) y se convierten y facturan en USD al tipo de cambio actual. El único token que estableces en el handle `ads` debe incluir los scopes del píxel junto con los scopes de campaña (`ad_campaign:create` y `company:basic:read`), en lugar de usar un token distinto para cada elemento.

> [card] [AdsAgreementElement](https://docs.whop.com/es/elements/latest/ads/ads-agreement.md)
>
> Firma el Whop Ads Services and Payment Authorization Agreement de una cuenta. Al guardar la facturación del gasto publicitario de la cuenta se abre el acuerdo; hasta que un representante autorizado lo firme, no se puede lanzar ninguna campaña. El firmante escribe su nombre legal completo y, opcionalmente, su cargo, acepta los términos, y la firma escrita se archiva junto con el acuerdo. Una vez firmado, muestra quién lo firmó y cuándo; antes de configurar la facturación no hay nada que firmar y así lo indica. `campaign-creator` lo abre por sí solo sobre el creador cuando un lanzamiento necesita una firma, así que móntalo tú mismo solo para ofrecer la firma por adelantado, por ejemplo en una página de ajustes o de onboarding.


## Related topics

- [List Ads](https://docs.whop.com/es/api-reference/ads/list-ads.md)
- [API de Ads](https://docs.whop.com/es/api-reference/ads/ad.md)
- [AdsAgreementElement](https://docs.whop.com/es/elements/latest/ads/ads-agreement.md)
