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:

npm install @usecapsule/react-sdk

pnpm install @usecapsule/react-sdk

yarn add @usecapsule/react-sdk

Core SDK

If you'd prefer to use the Capsule SDK functionality directly with your own UI components:

npm install @usecapsule/web-sdk

pnpm install @usecapsule/web-sdk

yarn add @usecapsule/web-sdk

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.

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:

App.tsx

import React, { useState } from "react";
import Capsule, { Environment, CapsuleModal } from "@usecapsule/react-sdk";
// Import styles if using v3.5.0 or greater of `@usecapsule/react-sdk`
import "@usecapsule/react-sdk/styles.css";

// Initialize Capsule SDK with your API key and environment
const capsule = new Capsule(Environment.BETA, process.env.CAPSULE_API_KEY);

const App = () => {
  const [isOpen, setIsOpen] = useState(false); // Use any state management you wish, this is purely an example!

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Sign in With Email</button>

      <CapsuleModal capsule={capsule} isOpen={isOpen} onClose={() => setIsOpen(false)} />
    </div>
  );
};

export default App;

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 Instance
A constructorOpts object can be passed into the Capsule() 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.

App.tsx

const constructorOpts = {
  // Email configurations
  emailTheme: "light",
  emailPrimaryColor: "#007bff",
  githubUrl: "https://github.com/example",
  linkedinUrl: "https://www.linkedin.com/company/example",
  xUrl: "https://x.com/example",
  homepageUrl: "https://example.com",
  supportUrl: "mailto:support@example.com", // Can also be a webpage URL
};

const capsule = new Capsule(
  Environment.BETA,
  process.env.REACT_APP_CAPSULE_API_KEY,
  constructorOpts // Customized constructorOpts
);

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.

App.tsx

<CapsuleModal
  capsule={capsule}
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  appName="Your App Name" // Name of your application
  logo="https://example.com/logo.png" // URL for your logo
  theme={{
    backgroundColor: "#ffffff", // Background color of the modal
    foregroundColor: "#000000", // Foreground/highlight color of the modal
  }}
  oAuthMethods={["GOOGLE", "TWITTER", "DISCORD"]} // Social login options
/>

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:

App.tsx

import { Capsule, Environment } from "@usecapsule/web-sdk";
const capsule = new Capsule(Environment.BETA, YOUR_API_KEY);

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.

PreviousInitial Setup NextReact Native Setup

Last updated 1 month ago

Introduction

Prerequisites

Installation

Dependency Installation

Setup

Capsule Modal Setup

Customizing the Capsule Instance

Customizing the CapsuleModal Component

On-Ramp Configuration

Core SDK Setup