Web Modal & SDK Setup
Introduction
The Capsule SDK for Web allows you to easily integrate secure and scalable wallet functionalities into your web applications. This guide covers the installation, setup, and usage of the Capsule SDK, including handling authentication flows via the Capsule Modal or direct SDK usage with custom UI components.
Prerequisites
A web project using frameworks like React, Vue, or plain JavaScript.
An API key from the Capsule team. Request an API key.
Basic knowledge of web development.
Installation
Dependency Installation
To install the Capsule SDK and required dependencies, use one of the following commands based on your package manager:
Capsule Modal (Recommended)
If you'd like to use our React modal components for easier integration:
Core SDK
If you'd prefer to use the Capsule SDK functionality directly with your own UI components:
Setup
Follow these comprehensive steps to seamlessly integrate the Capsule SDK into your web project. Whether you choose to use the Capsule Modal for easy integration with React components or the Core SDK for more custom UI solutions, this guide will ensure a smooth setup process and optimal functionality.
NOTE: There are two hosted Capsule environments, Environment.BETA
is for development and testing and Environment.PROD
is for production. If you prefer, you can also reference Beta as Environment.DEVELOPMENT.
If you're referencing Environments as strings, for example in a .env
file, you should refer to these environments as BETA
and PRODUCTION
, respectively.
Capsule Modal Setup
If you're using the CapsuleModal
component, simply import the Modal Component into your application and configure it to your preferences. If you're using Next.js or a Server-Side rendering framework, you may need to do this via a dynamic import.
Import and Initialize the Capsule Modal:
Configuration:
Now, let's make your Capsule integration uniquely yours! Customizing your Capsule instance and CapsuleModal is recommended and highly encouraged to match your application's brand, making the user experience seamless and engaging.
Customizing the Capsule InstanceA
constructorOpts
object can be passed into theCapsule()
constructor as a third argument, allowing for the branding of the Capsule Passkey portal and emails. The following is an example object, with further customizations accessible in the Customize Capsule section of the docs.
Customizing the CapsuleModal Component
Enhance your CapsuleModal with customization options to align it with your applicationβs branding. Hereβs an example of how you can customize the CapsuleModal
component. For more detailed customization options, check out the Customize Capsule section of the docs.
For the full list of configuration options on both Capsule
and CapsuleModal
, check out the Customize Capsule page.
On-Ramp Configuration
The Capsule Modal currently supports crypto on-ramping from Stripe and Ramp. For detailed setup instructions, see the full documentation
Core SDK Setup
If you prefer to use your own custom UI components and handle the authentication and user creation flows yourself, you can use the Core SDK. This option provides flexibility for developers to implement and control the user experience according to their application's needs.
Simply import the Capsule SDK into your application and initialize it with your configurations. This approach is ideal for those who want to fully customize the integration while still leveraging the secure and scalable functionalities of Capsule.
Import and Initialize the Core SDK:
Implementing Custom UI:
If you are using the Core SDK directly, you'll need to implement your own logic to connect the different auth steps. This approach is more nuanced, we recommend studying one of the Examples first and basing your integration on them. Below are the key methods you want to focus on:
Key Methods:
checkIfUserExists(email: string)
: Checks if a user already exists.isFullyLoggedIn()
: Checks if a session is active and a wallet exists.initiateUserLogin(email:string)
: Initiates a login with a web Auth URL for login.waitForLoginAndSetup()
: Waits for the session to be active and sets up the user.createUser(email: string)
: Creates a new user and sends a verification email.verifyEmail(code: string)
: Verifies the user's email and retrieves the webAuth URL.waitForPasskeyAndCreateWallet()
: Waits for the user to complete account creation and create a wallet.
Last updated