Skip to main content
Cette page documente @whop/elements@1.10.0 et @whop/elements-react@1.10.0.
Whop Elements sont des composants d’interface hébergés et personnalisables que vous intégrez à votre propre site. Chaque élément s’affiche dans un frame isolé servi depuis le CDN de Whop. Vous installez un package léger et entièrement typé, et le code des éléments se met à jour de lui-même.
Whop Elements sont des composants d’interface personnalisables que vous pouvez importer dans votre application iOS. Ils sont distribués sous la forme d’un unique package Swift SPM. Chacun est une simple vue SwiftUI qui récupère ses propres données et gère son propre état : un écran de solde se résume donc à quelques vues dans un VStack au lieu d’une couche réseau et d’un view model. Ajoutez le package, indiquez au SDK comment récupérer un jeton d’accès, et placez les éléments dans votre hiérarchie de vues.
Whop Elements sont des composants d’interface personnalisables que vous pouvez intégrer à une application React Native. Ce sont de vrais composants React Native, pas des web views : les tuiles de moyens de paiement, le formulaire d’adresse et les champs de carte sont tous des saisies natives, et Apple Pay et Google Pay ouvrent la feuille de paiement propre à la plateforme. Installez le package, indiquez au SDK comment récupérer un jeton d’accès, et montez les éléments.

Installation

Ajoutez le package à votre Package.swift (ou File → Add Package Dependencies dans Xcode) :
Installez le SDK :

Prérequis

Content Security Policy

contentSecurityPolicy() de @whop/elements renvoie toutes les sources de ce tableau, pour l’environnement que vous transmettez. Les lignes concernant le travail côté page s’exécutent sur votre page, pas dans un frame. Les scripts que les éléments chargent pour Apple Pay, Google Pay et PayPal et pour la liaison de compte bancaire Plaid proviennent d’autres entreprises et peuvent charger des ressources au-delà de ces lignes. Consultez aussi les recommandations Content Security Policy de chaque fournisseur.
Les éléments s’affichent dans des frames servis depuis cdn.whop.com. Une partie de leur travail s’exécute sur votre page et appelle api.whop.com depuis celle-ci, comme Apple Pay, Google Pay et PayPal et la liaison de compte bancaire Plaid. Si votre CSP bloque l’une de ces origines, vous obtenez un espace vide à la place de l’élément ou une requête en échec, et l’erreur n’apparaît que dans la console du navigateur.
Un élément modal assombrit votre page en arrière-plan avec un style inline. Un style-src qui n’autorise pas les styles inline laisse la page non assombrie, mais la modale fonctionne toujours.

Avant de commencer

Il vous faut deux choses :
  1. Un accountId. Un ID de compte, préfixé par biz_, ou un ID d’utilisateur, préfixé par user_, pour les propres données de l’utilisateur. Les interfaces de paiement acceptent plutôt un plan ou un montant, et chaque page d’élément indique ce dont il a besoin.
  2. Un endpoint serveur qui crée un jeton d’accès, limité aux éléments que vous montez.
Ne placez jamais une clé API Whop dans du code navigateur. Elle permet de créer des jetons, donc toute personne qui ouvre les outils de développement du navigateur peut lire le compte. Créez le jeton sur votre serveur et n’envoyez que le jeton.
Votre serveur appelle Create Access Token avec le compte et les scopes dont les éléments ont besoin :

Prérequis

Avant de commencer

Il vous faut deux choses :
  1. Un accountId. Un ID de compte, préfixé par biz_, ou un ID d’utilisateur, préfixé par user_, pour le propre solde de l’utilisateur.
  2. Un endpoint serveur qui crée un jeton d’accès pour le compte. N’embarquez jamais une clé API Whop dans l’application. Elle permet de créer des jetons, donc toute personne qui l’extrait peut lire le compte. Créez le jeton sur votre serveur et ne renvoyez que celui-ci.
Un tag user_… lit les propres données de l’utilisateur, il utilise donc l’OAuth utilisateur (WhopSDK.configureWithOAuth) au lieu d’un jeton. Les vues de chat aussi.Votre serveur appelle Create Access Token avec le compte et le scope dont les éléments ont besoin :

Prérequis

Les deux gestionnaires de dépendances iOS fonctionnent. Le package fournit à la fois un ios/Package.swift et un podspec, et la chaîne d’outils choisit l’un des deux. L’autolinker Swift Package Manager de React Native privilégie le Package.swift, donc une application déjà sur SPM n’est pas affectée par le podspec. Une application sur CocoaPods, ce qui inclut aujourd’hui toutes les applications Expo, se lie via le podspec et n’a besoin de rien d’autre. La version minimale de React Native est plus élevée avec SPM car Package.swift lie deux XCFrameworks header-only apparus pour la première fois dans la 0.87.
Le code natif est du Swift et du Kotlin générés via React Native Codegen : rien ici ne vous demande de modifier à la main de l’Objective-C ou du Java, et il n’y a aucune dépendance native peer à installer.

Avant de commencer

Il vous faut deux choses :
  1. Un accountId. Un ID d’entreprise, préfixé par biz_.
  2. Un endpoint serveur qui génère un jeton d’accès pour ce compte. N’embarquez jamais une clé API Whop dans l’application : elle permet de créer des jetons, donc toute personne qui l’extrait peut agir en tant que compte. Générez le jeton sur votre serveur et ne renvoyez que celui-ci.
Votre serveur appelle Create Access Token et renvoie le résultat à getToken.

Monter votre premier élément

Une application complète. configure s’exécute une fois au lancement, et les éléments affichent un indicateur de chargement jusqu’à ce qu’il aboutisse, donc rien n’entre en concurrence avec lui :
Un checkout complet. <WhopElements> contient le résolveur de jeton, <Payments> contient le débit, et les éléments entre les deux le collectent :
Vous préférez npm à la balise script ? loadWhop() injecte le même script hébergé et résout le constructeur global :

Authentification

Transmettez un accessToken lorsque vous créez le handle. Utilisez un seul jeton pour tout le handle, pas un par élément. Le handle envoie ce jeton à chaque élément qu’il contient, donc demandez tous les scopes dont vous avez besoin sur ce seul jeton. Chaque page d’élément liste les scopes qu’il lit.
Le jeton est une valeur que vous définissez, pas un callback appelé par le SDK. Définissez-en un nouveau avant son expiration :
Si vous omettez accessToken, les requêtes utilisent à la place le cookie de session de l’utilisateur. Cela fonctionne uniquement sur whop.com. L’API n’envoie pas Access-Control-Allow-Credentials sur les requêtes preflight cross-origin, donc une page sur votre propre domaine n’a pas de session de repli et doit transmettre un jeton.

Configuration globale

Tout ce que vous transmettez à la construction s’applique à chaque groupe d’éléments créé à partir de cette instance (les options propres à un handle peuvent prendre le dessus pour chaque groupe) :
Appearance
Personnalisation visuelle de chaque élément — theme (clair/sombre + palettes), variables (propriétés CSS personnalisées) et classes (déclarations de style par partie). Le schéma de couleurs est appliqué avant le premier affichage d’un élément, donc les pages sombres ne clignotent jamais en clair. Consultez Apparence.
string
Langue du texte de l’interface des éléments — l’une des langues intégrées à l’application ; toute autre valeur revient à la langue par défaut. Par défaut : "en".L’une des valeurs "en", "es", "zh", "nl", "pt", "de", "hu", "it", "fr", "ja", "pl" ou "tr".
"production" | "sandbox"
L’environnement de l’API Whop avec lequel communiquent les éléments — "sandbox" cible l’API sandbox (données de test ; aucun argent réel ne circule). Choisir un environnement est le seul moyen de changer l’endroit où les éléments envoient ce que saisit un acheteur, et les deux environnements appartiennent à Whop. L’environnement sandbox n’est pas encore disponible pour tous. Par défaut : "production".
boolean
Indique si les éléments peuvent afficher des notifications toast sur votre page — de brefs messages d’état (« Payment method added », « Payment failed ») affichés dans le coin inférieur droit. Définissez false pour les désactiver entièrement. Par défaut : true.
boolean
Ignore le pixel Whop. Par défaut, les éléments chargent le pixel publicitaire Whop sur une page qui ne l’exécute pas déjà, limité au compte pour lequel ils travaillent (l’accountId d’un groupe d’éléments, ou le vendeur du plan d’un checkout), et associent les analytics des éléments à l’ID visiteur du pixel, un lien d’identité ponctuel qui permet de rapprocher l’activité des éléments de vos données d’attribution publicitaire dans le graphe d’identité de Whop. Définissez true pour ne faire ni l’un ni l’autre. Les analytics d’utilisation elles-mêmes ne sont pas affectées (désactivez-les par handle avec analytics: false). Par défaut : false.
Avec React, le même objet passe par <WhopElements appearance={…} locale={…}>.L’option globale toasts est active sur cette page — le bouton ci-dessous en envoie un via le même canal que celui utilisé par les éléments, avec le thème de l’appearance de cette page :

Ce que gèrent les éléments, et ce qui vous revient

Chaque élément récupère ses propres données et affiche ses propres états de chargement, vide et d’erreur.Vous gérez la navigation et le stockage. Les éléments signalent les sélections et les résultats sous forme d’événements, et n’écrivent jamais dans votre base de données.L’exception est un flux qui quitte la page. Lorsqu’un élément accepte une returnUrl, il y redirige l’onglet, et l’acheteur peut donc se retrouver hors de votre page. L’acheteur y arrive après une étape externe échouée ou abandonnée aussi bien qu’après une étape réussie, avec status (succeeded, failed ou canceled) et l’ID de la tentative ajoutés à l’URL, donc la page de returnUrl doit lire status avant d’afficher un message de succès. Exécutez les commandes à partir des webhooks plutôt que d’un callback navigateur.Les éléments s’exécutent dans des frames, donc seules les valeurs sérialisables franchissent la frontière. Il n’y a pas de DOM partagé, et l’identité des objets n’est pas préservée.

Dépannage

Éléments disponibles

Payments

Encaissez un paiement à partir d’un ID plan_ ou d’une devise et d’un montant inline, ou enregistrez un moyen de paiement sans débit avec mode: "setup".

Verifications

Collecte et vérifie les informations d’identité d’un compte.

Checkout

Pilote un checkout hébergé complet pour un ou plusieurs plans — récapitulatif de prix détaillé, codes promo, devise dans laquelle l’acheteur paie, et toute l’interface de collecte du paiement (les éléments de paiement, composés à l’intérieur) — via l’API des sessions de checkout Whop.

Ads

Un compte publicitaire.

Tracking

L’audience suivie d’un compte : toutes les personnes vues par son pixel, et tous les événements qu’elles ont effectués.

Wallet

Pilote les interfaces financières d’un compte.

Websites

Les sites web d’un compte : chaque site créé sur whop.site ainsi que chaque domaine signalé par le Whop Pixel, avec le trafic et le revenu attribué par domaine.

Dashboard

Les interfaces du tableau de bord propres à un compte, intégrées à votre site.

Delivery

Suivi des livraisons pour les clients d’une entreprise.

Chat

Chat en temps réel avec une liste de canaux et une recherche de messages.

Étapes suivantes

  • Apparence : thèmes, variables CSS et restylage par partie
  • Create Access Token : l’endpoint à partir duquel votre serveur génère les jetons

Authentification

getToken() est votre unique point d’intégration, et le SDK l’appelle à nouveau avant l’expiration du jeton : renvoyez donc un nouveau jeton à chaque fois plutôt que d’en mettre un en cache :
Configurez une seule fois, n’importe où au-dessus des éléments. WhopSDK est global au processus, donc un second appel n’est nécessaire que lorsque le compte change :
Le chat et les DM authentifient l’utilisateur plutôt qu’un compte, via OAuth : WhopSDK.configureWithOAuth(appId:).

Thèmes

.whopTheme(_:) se propage dans l’environnement SwiftUI, donc un seul appel applique le thème à chaque élément situé en dessous. Six rôles, chacun étant un WhopTint :
Les valeurs par défaut sont accent: .blue, neutral: .gray, danger: .red, info: .sky, success: .green, warning: .amber. WhopTheme.default regroupe les six. Les vues suivent d’elles-mêmes l’apparence claire/sombre du système.

Ce que gèrent les éléments, et ce qui vous revient

Chaque vue récupère ses propres données et affiche ses propres états de chargement, vide et d’erreur, y compris une nouvelle tentative. La navigation vous revient : les callbacks de sélection vous transmettent une valeur et n’affichent jamais d’écran.

Dépannage

Disponible sur iOS

Les vues wallet, chacune avec un simulateur en direct sur sa page :WhopChatView et WhopDMsListView sont fournis dans le même package pour le chat authentifié par l’utilisateur. Consultez le README.

Paiements sur iOS

Les éléments de paiement sont fournis dans leur propre package, whopio/elements-swift, qui expose un module Elements. Le module du SDK wallet est WhopElements, donc les deux s’installent côte à côte :
Le module est Elements, et non WhopElements, donc import Elements est la seule ligne qui change. La configuration diffère aussi, et elle se répartit comme dans SwiftUI : la configuration est héritée de la racine de l’application, et un débit constitue un scope. Rien ne nécessite de jeton, car un jeton de confirmation est généré à partir de ce que l’acheteur a saisi, puis confirmé sur votre serveur :
Les données de carte sont capturées par des champs hébergés isolés PCI et n’entrent jamais dans votre processus. Stylisez l’ensemble avec .whopElementsAppearance(_:) plutôt qu’avec .whopTheme(_:).

Authentification

getToken est votre unique point d’intégration, et le SDK l’appelle avant chaque requête : renvoyez donc un nouveau jeton plutôt que d’en mettre un en cache :
Un élément qui ne nécessite aucun identifiant fonctionne sans lui, vous pouvez donc afficher un formulaire de carte avant de connecter votre backend.

Encaisser un paiement

La collecte et la confirmation sont séparées, et cette séparation est délibérée : l’application ne voit jamais de numéro de carte et votre serveur ne fait jamais confiance au client.
  1. Les éléments collectent. Les numéros de carte passent directement des champs isolés PCI à un jeton, sans jamais transiter par votre code.
  2. createConfirmationToken() renvoie un jeton de confirmation, que vous pouvez envoyer en toute sécurité à votre propre backend.
  3. Votre backend confirme le paiement avec l’API Whop.
  4. Si l’API répond que le paiement nécessite une action supplémentaire de l’acheteur, transmettez son client_secret à handleNextAction() et le SDK exécute l’étape 3D Secure ou de redirection.

Redirections et 3D Secure

Les étapes hors application ouvrent le navigateur système (ASWebAuthenticationSession sur iOS, Custom Tabs sur Android), jamais une WebView, de sorte que la page de l’émetteur reste en dehors du périmètre de confiance de votre application et que ses cookies restent hors du stockage de votre application.Définissez returnUrl sur <Payments> avec une URL https que vous hébergez. L’API refuse tout ce qui n’est pas https ou loopback (PaymentsApi::ValidateReturnUrl), donc un schéma d’application personnalisé ne fonctionnera pas ici — et vous n’en avez pas besoin : handleNextAction interroge le paiement jusqu’à son état final et ferme lui-même le navigateur, plutôt que d’attendre un deep link de retour vers votre application.

Apple Pay et Google Pay

Les tuiles de wallet apparaissent dès que la plateforme peut présenter une feuille de paiement, et il n’y a rien à configurer pour l’un ou l’autre. Apple Pay utilise le marchand enregistré sur le compte Whop, donc votre application n’a besoin ni d’identifiant marchand ni de capability Xcode. googlePayMerchantName sur <Payments> définit uniquement le nom affiché dans la feuille.

Thèmes

appearance sur <WhopElements> applique le thème à chaque élément situé en dessous, avec le même objet theme que celui accepté par les éléments web. Consultez Apparence.

Ce que gèrent les éléments, et ce qui vous revient

Chaque élément récupère ses propres données et affiche ses propres états de chargement, vide et d’erreur. La navigation et la soumission vous reviennent : les éléments signalent via onChange et n’affichent jamais d’écran ni n’appellent votre backend.

Dépannage

Disponible dans React Native

Les éléments de paiement :
  • PaymentElement : les tuiles de moyens de paiement et tout ce dont le moyen sélectionné a besoin
  • AddressElement : l’adresse de facturation au format du pays de l’acheteur
  • CardElement : numéro, date d’expiration et code de sécurité en un seul composant
  • CardFields : les trois mêmes champs, placés individuellement
  • EmailElement : l’e-mail de l’acheteur
  • TaxIdElement : un type et un numéro d’immatriculation
  • BrandingElement : la mention Powered by Whop, obligatoire sur chaque formulaire
Les éléments de checkout :