Cette page documente
@whop/elements@1.10.0 et @whop/elements-react@1.10.0.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 :Options
Transmettez-les àwhop.ads.create({ … }), ou comme props sur <Ads> avec React.
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 : "".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.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 : {}.Personnalisation visuelle des éléments de ce groupe. Remplace le
WhopElements({ appearance }) global. Modifiez-la en direct avec update({ appearance }).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.
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.
Méthodes
Appelez-les sur le handle Ads obtenu viawhop.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
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 :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)BillingSetupElement
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.
CampaignCreatorElement
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.AdsAgreementElement
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.
