Skip to main content
Esta página documenta @whop/elements@1.10.0 y @whop/elements-react@1.10.0.
Whop Elements son componentes de interfaz alojados y personalizables que incrustas en tu propio sitio. Cada elemento se renderiza en un frame aislado servido desde la CDN de Whop. Instalas un paquete ligero y completamente tipado, y el código de los elementos se mantiene actualizado por sí solo.
Whop Elements son componentes de interfaz personalizables que puedes importar en tu app de iOS. Se distribuyen como un único paquete SPM de Swift. Cada uno es una vista SwiftUI normal que obtiene sus propios datos y gestiona su propio estado, de modo que una pantalla de saldo son un par de vistas en un VStack en lugar de una capa de red y un view model. Añade el paquete, indica al SDK cómo obtener un token de acceso y coloca los elementos en tu jerarquía de vistas.
Whop Elements son componentes de interfaz personalizables que puedes incorporar a una app de React Native. Son componentes reales de React Native, no web views: los mosaicos de métodos de pago, el formulario de dirección y los campos de tarjeta son todos entradas nativas, y Apple Pay y Google Pay abren la hoja propia de la plataforma. Instala el paquete, indica al SDK cómo obtener un token de acceso y monta los elementos.

Instalación

Añade el paquete a tu Package.swift (o usa File → Add Package Dependencies en Xcode):
Instala el SDK:

Requisitos

Política de seguridad de contenido

contentSecurityPolicy() de @whop/elements devuelve todas las fuentes de esta tabla para el entorno que le pases. Las filas del trabajo del lado de la página se ejecutan en tu página, no en un frame. Los scripts que cargan los elementos para Apple Pay, Google Pay y PayPal y para la vinculación de cuentas bancarias con Plaid provienen de otras empresas y pueden cargar recursos más allá de estas filas. Consulta también las indicaciones sobre Content Security Policy de cada proveedor.
Los elementos se renderizan en frames servidos desde cdn.whop.com. Parte de su trabajo se ejecuta en tu página y llama a api.whop.com desde ella, como Apple Pay, Google Pay y PayPal y la vinculación de cuentas bancarias con Plaid. Si tu CSP bloquea cualquiera de los dos orígenes, obtienes un espacio en blanco en lugar del elemento o una solicitud fallida, y el error solo aparece en la consola del navegador.
Un elemento modal oscurece tu página detrás de él con un estilo en línea. Un style-src que no permite estilos en línea deja la página sin oscurecer, pero el modal sigue funcionando.

Antes de empezar

Necesitas dos cosas:
  1. Un accountId. Un ID de cuenta, con prefijo biz_, o un ID de usuario, con prefijo user_, para los datos propios del usuario. Las superficies de pago aceptan en su lugar un plan o un importe, y cada página de elemento indica cuál necesita.
  2. Un endpoint de servidor que cree un token de acceso, con el alcance de los elementos que montes.
Nunca pongas una clave de API de Whop en código del navegador. Crea tokens, así que cualquiera que abra las herramientas de desarrollo del navegador puede leer la cuenta. Crea el token en tu servidor y envía solo el token.
Tu servidor llama a Create Access Token con la cuenta y los alcances que necesitan los elementos:

Requisitos

Antes de empezar

Necesitas dos cosas:
  1. Un accountId. Un ID de cuenta, con prefijo biz_, o un ID de usuario, con prefijo user_, para el saldo propio del usuario.
  2. Un endpoint de servidor que cree un token de acceso para la cuenta. Nunca incluyas una clave de API de Whop en la app. Crea tokens, así que cualquiera que la extraiga puede leer la cuenta. Crea el token en tu servidor y devuelve solo eso.
Una etiqueta user_… lee los datos propios del visitante, por lo que usa OAuth del visitante (WhopSDK.configureWithOAuth) en lugar de un token. Las vistas de chat también.Tu servidor llama a Create Access Token con la cuenta y el alcance que necesitan los elementos:

Requisitos

Funciona cualquiera de los dos gestores de dependencias de iOS. El paquete incluye tanto un ios/Package.swift como un podspec, y las herramientas eligen uno. El autolinker de Swift Package Manager de React Native prefiere el Package.swift, así que el podspec no afecta a una app que ya usa SPM. Una app con CocoaPods, lo que hoy incluye todas las apps de Expo, se vincula mediante el podspec y no necesita nada más. La versión mínima de React Native es más alta con SPM porque Package.swift vincula dos XCFrameworks de solo cabeceras que se publicaron por primera vez en 0.87.
El código nativo es Swift y Kotlin generado mediante React Native Codegen: nada aquí te pide editar a mano Objective-C o Java, y no hay dependencias nativas complementarias que instalar.

Antes de empezar

Necesitas dos cosas:
  1. Un accountId. Un ID de empresa, con prefijo biz_.
  2. Un endpoint de servidor que genere un token de acceso para esa cuenta. Nunca incluyas una clave de API de Whop en la app: crea tokens, así que cualquiera que la extraiga puede actuar como la cuenta. Genera el token en tu servidor y devuelve solo eso.
Tu servidor llama a Create Access Token y devuelve el resultado a getToken.

Monta tu primer elemento

Una app completa. configure se ejecuta una vez al iniciar, y los elementos muestran un indicador de carga hasta que termina, así que nada compite con él:
Un checkout completo. <WhopElements> contiene el resolvedor del token, <Payments> contiene el cobro y los elementos entre ellos lo recopilan:
¿Prefieres npm en lugar de la etiqueta script? loadWhop() inyecta el mismo script alojado y resuelve el constructor global:

Autenticación

Pasa un accessToken al crear el handle. Usa un token para todo el handle, no uno por elemento. El handle envía ese token a todos los elementos que contiene, así que solicita en ese único token todos los alcances que necesites. Cada página de elemento enumera los alcances que lee.
El token es un valor que estableces tú, no un callback al que llama el SDK. Establece uno nuevo antes de que caduque:
Si omites accessToken, las solicitudes usan en su lugar la cookie de sesión del visitante. Esto funciona solo en whop.com. La API no envía Access-Control-Allow-Credentials en las solicitudes preflight de origen cruzado, así que una página en tu propio dominio no tiene ninguna sesión a la que recurrir y debe pasar un token.

Configuración global

Todo lo que pasas en la construcción se aplica a todos los grupos de elementos creados a partir de esa instancia (las opciones propias de un handle pueden anularlo por grupo):
Appearance
Personalización visual para todos los elementos: theme (claro/oscuro + paletas), variables (propiedades personalizadas de CSS) y classes (declaraciones de estilo por parte). El esquema de color se aplica antes del primer pintado de un elemento, así que las páginas oscuras nunca muestran un destello claro. Consulta Appearance.
string
Configuración regional para el texto de la interfaz de los elementos: una de las configuraciones regionales incluidas en la app; cualquier otro valor recurre a la configuración regional predeterminada. Por defecto es "en".Uno de "en", "es", "zh", "nl", "pt", "de", "hu", "it", "fr", "ja", "pl" o "tr".
"production" | "sandbox"
Con qué entorno de la API de Whop se comunican los elementos: "sandbox" apunta a la API de sandbox (datos de prueba; no se mueve dinero real). Elegir un entorno es la única forma de cambiar adónde envían los elementos lo que escribe un comprador, y ambos entornos son de Whop. El entorno sandbox todavía no está disponible de forma general. Por defecto es "production".
boolean
Si los elementos pueden mostrar notificaciones toast en tu página: mensajes de estado breves (“Payment method added”, “Payment failed”) que se muestran en la esquina inferior derecha. Establécelo en false para desactivarlas por completo. Por defecto es true.
boolean
Omite el píxel de Whop. Por defecto, los elementos cargan el píxel de anuncios de Whop en una página que todavía no lo ejecuta, limitado a la cuenta para la que trabajan (el accountId de un grupo de elementos, o el vendedor del plan de un checkout), y vinculan las analíticas de los elementos al ID de visitante del píxel, un vínculo de identidad único que permite unir la actividad de los elementos con tus datos de atribución de anuncios en el grafo de identidad de Whop. Establécelo en true para no hacer ninguna de las dos cosas. Las analíticas de uso en sí no se ven afectadas (desactívalas por handle con analytics: false). Por defecto es false.
En React, el mismo objeto se pasa en <WhopElements appearance={…} locale={…}>.La opción global toasts está activa en esta página: el botón de abajo envía una a través del mismo canal que usan los elementos, con el tema del appearance de esta página:

De qué se encargan los elementos y de qué te encargas tú

Cada elemento obtiene sus propios datos y renderiza sus propios estados de carga, vacío y error.Tú te encargas de la navegación y el almacenamiento. Los elementos informan de las selecciones y los resultados como eventos, y nunca escriben en tu base de datos.La excepción es un flujo que sale de la página. Cuando un elemento acepta una returnUrl, navega la pestaña hasta ella, por lo que el comprador puede acabar fuera de tu página. El comprador llega ahí tanto después de un paso externo fallido o abandonado como después de uno exitoso, con status (succeeded, failed o canceled) y el ID del intento añadidos a la URL, así que la página en returnUrl tiene que leer status antes de mostrar un mensaje de éxito. Realiza el cumplimiento a partir de webhooks en lugar de un callback del navegador.Los elementos se ejecutan en frames, así que solo los valores serializables cruzan el límite. No hay DOM compartido y la identidad de los objetos no se conserva.

Solución de problemas

Elementos disponibles

Payments

Cobra un pago a partir de un ID plan_ o de una moneda e importe en línea, o guarda un método de pago sin cobrar con mode: "setup".

Verifications

Recopila y verifica la información de identidad de una cuenta.

Checkout

Gestiona un checkout alojado completo para uno o más planes (resumen de precios detallado, códigos promocionales, la moneda en la que paga el comprador y toda la superficie de cobro, con los elementos de pagos compuestos dentro) contra la API de sesiones de checkout de Whop.

Ads

Una cuenta publicitaria.

Tracking

La audiencia rastreada de una cuenta: todas las personas que ha visto su píxel y todos los eventos que realizaron.

Wallet

Gestiona las superficies de dinero de una cuenta.

Websites

Los sitios web de una cuenta: todos los sitios creados en whop.site más todos los dominios de los que informa el Whop Pixel, con el tráfico y los ingresos atribuidos por dominio.

Dashboard

Las superficies del propio panel de una cuenta, incrustadas en tu sitio.

Delivery

Seguimiento de entregas para los clientes de una empresa.

Chat

Chat en tiempo real con una lista de canales y búsqueda de mensajes.

Siguientes pasos

Autenticación

getToken() es tu único punto de integración, y el SDK lo llama de nuevo antes de que caduque el token, así que devuelve un token nuevo cada vez en lugar de almacenar uno en caché:
Configúralo una vez, en cualquier lugar por encima de los elementos. WhopSDK es global para el proceso, así que solo hace falta una segunda llamada cuando cambia la cuenta:
El chat y los mensajes directos autentican al visitante en lugar de a una cuenta, mediante OAuth: WhopSDK.configureWithOAuth(appId:).

Temas

.whopTheme(_:) se propaga a través del entorno de SwiftUI, así que una sola llamada aplica el tema a todos los elementos que hay debajo. Seis roles, cada uno un WhopTint:
Los valores por defecto son accent: .blue, neutral: .gray, danger: .red, info: .sky, success: .green, warning: .amber. WhopTheme.default incluye los seis. Las vistas siguen por sí solas la apariencia clara/oscura del sistema.

De qué se encargan los elementos y de qué te encargas tú

Cada vista obtiene sus propios datos y renderiza sus propios estados de carga, vacío y error, incluido un reintento. Tú te encargas de la navegación: los callbacks de selección te entregan un valor y nunca abren una pantalla.

Solución de problemas

Disponible en iOS

Las vistas de wallet, cada una con un simulador en vivo en su página:WhopChatView y WhopDMsListView se incluyen en el mismo paquete para el chat autenticado por el visitante. Consulta el README.

Payments en iOS

Los elementos de pagos se distribuyen en su propio paquete, whopio/elements-swift, que ofrece un módulo Elements. El módulo del SDK de wallet es WhopElements, así que ambos se instalan uno junto al otro:
El módulo es Elements, no WhopElements, así que import Elements es la única línea que cambia. La configuración también es distinta y se divide como lo hace SwiftUI: la configuración se hereda desde la raíz de la app, y un cobro es un ámbito. Nada necesita un token, porque el token de confirmación se genera a partir de lo que escribió el comprador y se confirma en tu servidor:
Los datos de la tarjeta se capturan mediante campos alojados aislados según PCI y nunca entran en tu proceso. Aplica estilo a todo con .whopElementsAppearance(_:) en lugar de .whopTheme(_:).

Autenticación

getToken es tu único punto de integración, y el SDK lo llama antes de cada solicitud, así que devuelve un token nuevo en lugar de almacenar uno en caché:
Un elemento que no necesita credenciales funciona sin él, así que puedes renderizar un formulario de tarjeta antes de conectar tu backend.

Cobrar un pago

La recopilación y la confirmación están separadas, y la separación es deliberada: la app nunca ve un número de tarjeta y tu servidor nunca confía en el cliente.
  1. Los elementos recopilan. Los números de tarjeta van directamente de los campos aislados según PCI a un token, nunca a través de tu código.
  2. createConfirmationToken() devuelve un token de confirmación, que es seguro enviar a tu propio backend.
  3. Tu backend confirma el pago con la API de Whop.
  4. Si la API responde que el pago necesita algo más del comprador, pasa su client_secret a handleNextAction() y el SDK ejecuta el paso de 3D Secure o de redirección.

Redirecciones y 3D Secure

Los pasos fuera de la app abren el navegador del sistema (ASWebAuthenticationSession en iOS, Custom Tabs en Android), nunca un WebView, de modo que la página del emisor queda fuera del límite de confianza de tu app y sus cookies quedan fuera del almacén de tu app.Establece returnUrl en <Payments> en una URL https que alojes tú. La API rechaza cualquier cosa que no sea https o loopback (PaymentsApi::ValidateReturnUrl), así que un esquema de app personalizado no funcionará aquí, y tampoco lo necesitas: handleNextAction consulta el pago hasta que se resuelve y cierra el navegador por sí mismo, en lugar de esperar un deep link de vuelta a tu app.

Apple Pay y Google Pay

Los mosaicos de monedero aparecen una vez que la plataforma puede presentar una hoja, y no hay nada que configurar para ninguno de los dos. Apple Pay usa el comerciante registrado en la cuenta de Whop, así que tu app no necesita identificador de comerciante ni capability de Xcode. googlePayMerchantName en <Payments> solo establece el nombre que se muestra en la hoja.

Temas

appearance en <WhopElements> aplica el tema a todos los elementos que hay debajo, con el mismo objeto theme que aceptan los elementos web. Consulta Appearance.

De qué se encargan los elementos y de qué te encargas tú

Cada elemento obtiene sus propios datos y renderiza sus propios estados de carga, vacío y error. Tú te encargas de la navegación y el envío: los elementos informan mediante onChange y nunca abren una pantalla ni llaman a tu backend.

Solución de problemas

Disponible en React Native

Los elementos de pagos:
  • PaymentElement: los mosaicos de métodos y todo lo que necesita el método seleccionado
  • AddressElement: la dirección de facturación en el formato del propio país del comprador
  • CardElement: número, vencimiento y código de seguridad como un solo componente
  • CardFields: los mismos tres campos, colocados individualmente
  • EmailElement: el correo electrónico del comprador
  • TaxIdElement: un tipo y número de registro
  • BrandingElement: la marca Powered by Whop, obligatoria en todo formulario
Los elementos de checkout:
  • ExpressCheckoutElement: una pulsación de Apple Pay o Google Pay que paga todo un checkout, dentro de <Checkout>