The Capsule SDK for Flutter allows you to easily integrate secure and scalable wallet functionalities into your mobile applications. This guide covers the installation, setup, and usage of the Capsule SDK, including handling authentication flows.

Prerequisites

To use Capsule, you need an API key. This key authenticates your requests to Capsule services and is essential for integration.

Don’t have an API key yet? You can request access to the Capsule SDK by completing the Developer Access Form.

Dependency Installation

To install the Capsule SDK and required dependencies, use the following command:

flutter pub add capsule

Project Setup

To set up associated domains for passkey functionality in your Flutter project, you need to configure both iOS and Android platforms:

Associated Domains

To enable passkeys on iOS, you need to set up associated domains in your Xcode project:

  1. Open your Flutter project’s iOS folder in Xcode
  2. Select your target and go to “Signing & Capabilities”
  3. Click ”+ Capability” and add “Associated Domains”
  4. Add the following domains:
    • webcredentials:app.beta.usecapsule.com
    • webcredentials:app.usecapsule.com

For more details, see the Apple Developer documentation.

Important: You must register your teamId + bundleIdentifier with the Capsule team to set up associated domains. For example, if your Team ID is A1B2C3D4E5 and Bundle Identifier is com.yourdomain.yourapp, provide A1B2C3D4E5.com.yourdomain.yourapp to Capsule. This is required by Apple for passkey security. Allow up to 24 hours for domain propagation.

Using the Capsule SDK

The Capsule SDK provides two main authentication flows: creating a new user and logging in an existing user. Both flows utilize passkeys via WebView for secure and seamless authentication. Follow the steps below to implement these flows in your Flutter application.

Create New User

This flow guides you through the process of registering a new user, verifying their email, and setting up their wallet.

1

Check User Existence

First, check if a user with the given email already exists in the Capsule system:

Future<bool> checkUserExists(String email) async {
  try {
    return await _capsule.checkIfUserExists(email);
  } catch (e) {
    print("Error checking user existence: $e");
    return false;
  }
}
2

Create New User

If the user doesn’t exist, create a new account. This will automatically trigger a verification email to be sent:

Future<void> createUser(String email) async {
  try {
    await _capsule.createUser(email);
    print("User created. Verification email sent.");
  } catch (e) {
    print("Error creating user: $e");
  }
}
3

Verify Email

Once the user receives the verification code, verify their email to obtain a biometrics ID:

Future<String?> verifyEmail(String verificationCode) async {
  try {
    final biometricsId = await _capsule.verifyEmail(verificationCode);
    print("Email verified successfully");
    return biometricsId;
  } catch (e) {
    print("Error verifying email: $e");
    return null;
  }
}
4

Generate Passkey

Use the biometrics ID to generate a passkey for the user, which will be used for future authentications:

Future<void> generatePasskey(String email, String biometricsId) async {
  try {
    await _capsule.generatePasskey(email, biometricsId);
    print("Passkey generated successfully");
  } catch (e) {
    print("Error generating passkey: $e");
  }
}
5

Create User Wallet

Finally, create a wallet for the user. This step will provide a recovery secret that should be securely stored:

Future<void> createUserWallet() async {
  try {
    final walletResult = await _capsule.createWallet(skipDistribute: false);
    final wallet = walletResult.wallet;
    print("Wallet created: ${wallet.address}");
    // Store or display the wallet.recoverySecret securely
  } catch (e) {
    print("Error creating wallet: $e");
  }
}

It’s crucial to securely store or display the wallet.recoverySecret. This secret is necessary for account recovery if the user loses access to their device.

Login Existing User

This flow demonstrates how to authenticate an existing user using their email and passkey.

1

Initiate User Login

Start the login process by initiating the user login. This will return a URL for passkey authentication:

Future<String> initiateUserLogin(String email) async {
  try {
    return await _capsule.initiateUserLogin(email);
  } catch (e) {
    print("Error initiating user login: $e");
    rethrow;
  }
}
2

Complete Login Process

After the user authenticates via the WebView, complete the login process by waiting for the setup to finish:

Future<void> completeLogin() async {
  try {
    await _capsule.waitForLoginAndSetup();
    print("User logged in successfully");
  } catch (e) {
    print("Error completing login: $e");
  }
}

Examples

To help you get started with the Capsule Flutter SDK, we’ve prepared a comprehensive example:

Capsule Flutter Example

Capsule Flutter Example

Explore the Capsule Flutter Integration Example repository

This example repository demonstrates how to handle user authentication, wallet creation, and signing messages using the Capsule SDK in a Flutter application.

Next Steps

After integrating Capsule, you can explore other features and integrations to enhance your Capsule experience. Here are some resources to help you get started:

Ecosystems

Learn how to use Capsule with popular Web3 clients and wallet connectors. We’ll cover integration with key libraries for EVM, Solana, and Cosmos ecosystems.

If you’re ready to go live with your Capsule integration, make sure to review our go-live checklist:

Go-Live Checklist
Go-Live Checklist

Go-Live Checklist

Review our go-live checklist to ensure you've configured all necessary settings before launching your Capsule integration.

Troubleshooting

If you encounter issues during the integration or usage of the Capsule SDK in your Flutter application, here are some common problems and their solutions:

For more detailed troubleshooting and solutions specific to Flutter, please refer to our comprehensive troubleshooting guide:

Flutter Troubleshooting Guide

Access our detailed troubleshooting guide for solutions to common integration and usage issues with the Capsule SDK in Flutter environments.

Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our support team for assistance. To help us serve you better, include the following information in your support request:

  1. 1

    A detailed description of the problem you’re encountering.

  2. 2

    Any relevant error messages or logs.

  3. 3

    Steps to reproduce the issue.

  4. 4

    Details about your system or environment (e.g., device, operating system, software version).

Providing this information will enable our team to address your concerns more efficiently.