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

> Un compte publicitaire. Limitez-le à un compte Whop avec `accountId` — le compte publicitaire sous-jacent est attribué côté serveur et n'apparaît jamais ici — puis montez `reporting` pour voir ce que le compte a dépensé et ce que cela a rapporté, `campaign-creator` pour créer une campagne, ou `ads-agreement` pour signer le contrat Whop Ads requis pour un lancement.

> [!NOTE]
>
> Cette page documente `@whop/elements@1.10.0` et `@whop/elements-react@1.10.0`.

*Depuis `v1.0.0`.*

## Playground

Assemblez les éléments avec des données d'exemple. Manipulez les contrôles, ajoutez et organisez des éléments, et observez les événements se déclencher en direct :

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

## Options

Transmettez-les à `whop.ads.create({ … })`, ou comme props sur `<Ads>` avec React.

**accountId** `string`

ID du compte Whop, préfixé par `biz_`, dont la publicité est lue. Obligatoire ; il ne s'agit pas d'un ID de compte publicitaire. Par défaut : `""`.

**accessToken** `string`

Un jeton à portée limitée avec lequel chaque surface de ce handle lit et écrit. **Émettez un seul jeton pour tout le handle, et non un par élément.** Déterminez les scopes de chaque élément que vous allez monter, demandez-les sur un seul jeton et définissez-le ici — le handle projette cet identifiant unique dans le frame de chaque élément : un second jeton par surface n'apporte donc rien et vous laisse plusieurs dates d'expiration à suivre au lieu d'une. Émettez-le sur votre serveur avec `POST /api/v1/access_tokens` et définissez-en un nouveau avec `update({ accessToken })` avant son expiration. Tout monter nécessite `ad_campaign:read`/`:create`, `ad_group:read`, `ad:read`, `stats:read`, les scopes `:update`/`:delete` utilisés par les actions de ligne du tableau, `company:basic:read` pour les vérifications de pixel effectuées par `campaign-creator`, et `payment:charge` ainsi que `user:email:read` pour ajouter une carte de dépenses publicitaires ; les emplacements de facturation listent les cartes enregistrées et les wallets utilisables avec `member:payment_methods:read`. Monter moins de surfaces permet de demander moins de scopes — toujours sur le même jeton. S'il est omis, les appels utilisent la session du visiteur, qui ne répond qu'en same-origin.

**links** `CrossLinksConfig`

L'endroit de votre site vers lequel pointent les nombres de clics et de résultats du `table` de reporting — généralement les pages où vous avez monté les éléments `people` et `events` du namespace `tracking`. `people` et `events` sont des URL de base absolues (`https://…`) ; le tableau y ajoute les mêmes paramètres de requête que ceux que ces éléments acceptent comme props (`?source=whop:adcamp_…:*&event=…&from=…&to=…`), afin que la page cible puisse hydrater son élément directement à partir de son URL. Une URL relative serait résolue par rapport au frame de l'élément : elle est donc traitée comme non définie ; des liens non définis affichent les nombres comme de simples chiffres. Par défaut : `{}`.

**propriétés**

**people** `string`

**events** `string`

**person** `string`

**appearance** `Appearance`

Personnalisation visuelle des éléments de ce groupe. Remplace le `WhopElements({ appearance })` global. Modifiez-la en direct avec `update({ appearance })`.

**locale** `WhopElementsLocale`

Langue du texte de l'interface des éléments de ce groupe. Définissez-la sur l'une des langues intégrées à l'application pour remplacer la configuration globale. Toute autre valeur revient à la langue par défaut.

## Événements

Transmettez les callbacks dans les options de création ou dans les props React.

### `onBillingChanged`

Les moyens de paiement des dépenses publicitaires du compte ont changé et la modification est enregistrée. Les valeurs des emplacements sont les ID des moyens eux-mêmes — `payt_…` pour une carte, `ldgr_…` pour un solde ; un `backup` vide signifie qu'aucun n'est défini.

**payload** `object`

**propriétés**

**primary** `string` *required*

**backup** `string` *required*

### `onLoadingChange`

S'exécute lorsque l'état de chargement groupé change. La valeur est `true` tant qu'un élément monté est encore en cours de chargement.

**loading** `boolean`

## Méthodes

Appelez-les sur le handle Ads obtenu via `whop.ads.create({ … })` ou `useAds()`.

### `update`

Fusionne de nouvelles options de handle dans chaque élément monté. Avec React, modifiez plutôt les props du namespace.

**Paramètres**

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

### `destroy`

Détruit chaque élément et sous-contrôleur créé par ce handle, supprime le frame du contrôleur et libère ses abonnements. Vous pouvez l'appeler plusieurs fois, mais un handle détruit refuse tout autre appel — créez un nouveau handle pour recommencer. React supprime le groupe automatiquement lorsque le provider est démonté.

## Éléments

Les éléments montés par ce groupe. Chacun a sa propre page :

> [card] [Reporting](https://docs.whop.com/fr/elements/latest/ads/reporting)
>
> Les rapports d'un compte publicitaire : ce qu'il a dépensé et ce que cela a rapporté, sur une période, au niveau de détail que vous choisissez. Montez `chart`, `table` ou les deux — ils lisent la même période, la même règle d'attribution et la même sélection, de sorte que deux surfaces côte à côte ne peuvent jamais être en désaccord sur ce qu'elles affichent. La configuration `links` du handle `ads` relie les nombres de clics et de résultats du tableau à vos propres pages — celles où vous avez monté les éléments `people` et `events` du namespace `tracking`. *(sous-contrôleur, 3 éléments)*

> [card] [BillingSetupElement](https://docs.whop.com/fr/elements/latest/ads/billing-setup.md)
>
> Les moyens de paiement sur lesquels les dépenses publicitaires sont facturées : un moyen principal utilisé en premier, et un moyen de secours facultatif en cas d'échec. Les deux sont choisis parmi les moyens déjà enregistrés sur le compte, et la sélection d'un moyen l'enregistre immédiatement — il n'y a pas de validation séparée. L'ajout d'une carte ouvre un formulaire de carte par-dessus votre page, puis revient à l'emplacement qui l'a demandé. Le solde propre du compte apparaît à côté de ses cartes lorsque le compte en possède un.

> [card] [CampaignCreatorElement](https://docs.whop.com/fr/elements/latest/ads/campaign-creator.md)
>
> Le builder de campagnes publicitaires : objectif et budget, groupes d'annonces avec leur ciblage et leur calendrier, et les annonces elles-mêmes avec leurs créations — tout le parcours jusqu'au lancement. S'ouvre vide pour créer une nouvelle campagne, ou sur une campagne existante lorsque vous transmettez `campaignId`. Il exécute également le vérificateur de pixel : un lancement est conditionné à ce que l'événement de conversion du groupe d'annonces soit actif sur l'URL de destination, et l'assistant `pixel-setup` s'ouvre dans cet élément pour corriger une installation manquante. Un lancement est aussi conditionné à la signature du contrat Whop Ads par le compte : si ce n'est pas le cas, le handle ouvre `ads-agreement` par-dessus le builder et le lancement se poursuit une fois le contrat signé. Les budgets sont saisis et affichés dans la `ads_reporting_currency` du compte — la devise déjà utilisée par ses rapports — puis convertis et facturés en USD au taux de change en vigueur. L'unique jeton que vous définissez sur le handle `ads` doit porter les scopes du pixel en plus des scopes de campagne — `ad_campaign:create` et `company:basic:read` — plutôt que d'utiliser un jeton distinct par élément.

> [card] [AdsAgreementElement](https://docs.whop.com/fr/elements/latest/ads/ads-agreement.md)
>
> Signe le contrat Whop Ads Services and Payment Authorization Agreement pour un compte. L'enregistrement de la facturation des dépenses publicitaires du compte ouvre le contrat ; tant qu'un représentant autorisé ne l'a pas signé, aucune campagne ne peut être lancée. Le signataire saisit son nom légal complet et, facultativement, sa fonction, accepte les conditions, et la signature saisie est archivée avec le contrat. Une fois le contrat signé, l'élément indique qui l'a signé et quand ; tant que la facturation n'est pas configurée, il n'y a rien à signer et l'élément l'indique. `campaign-creator` l'ouvre lui-même par-dessus le builder lorsqu'un lancement nécessite une signature : ne le montez donc vous-même que pour proposer la signature à l'avance — sur une page de paramètres ou d'onboarding, par exemple.


## Related topics

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