Reclaim Protocol JavaScript SDK Integration Guide

This guide will walk you through integrating the Reclaim Protocol JavaScript SDK into your application. We'll create a simple React application that demonstrates how to use the SDK to generate proofs and verify claims.

Prerequisites

Before we begin, make sure you have:

An application ID from Reclaim Protocol.
An application secret from Reclaim Protocol.
A provider ID for the specific service you want to verify.

You can obtain these details from the Reclaim Developer Portal.

Step 1: Create a new React application

Let's start by creating a new React application:

npx create-react-app reclaim-app
cd reclaim-app

Step 2: Install necessary dependencies

Install the Reclaim Protocol SDK and a QR code generator:

npm install @reclaimprotocol/js-sdk react-qr-code

Step 3: Set up your React component

Replace the contents of src/App.js with the following code:

import React, { useState, useEffect } from 'react'
import { ReclaimProofRequest } from '@reclaimprotocol/js-sdk'
import QRCode from 'react-qr-code'

function App() {
  const [reclaimProofRequest, setReclaimProofRequest] = useState(null)
  const [requestUrl, setRequestUrl] = useState('')
  const [statusUrl, setStatusUrl] = useState('')
  const [proofs, setProofs] = useState(null)

  useEffect(() => {
    async function initializeReclaim() {
      const APP_ID = 'YOUR_APPLICATION_ID_HERE'
      const APP_SECRET = 'YOUR_APPLICATION_SECRET_HERE'
      const PROVIDER_ID = 'YOUR_PROVIDER_ID_HERE'

      const proofRequest = await ReclaimProofRequest.init(
        APP_ID,
        APP_SECRET,
        PROVIDER_ID
      )
      setReclaimProofRequest(proofRequest)
    }

    initializeReclaim()
  }, [])

  async function handleCreateClaim() {
    if (!reclaimProofRequest) {
      console.error('Reclaim Proof Request not initialized')
      return
    }

    const url = await reclaimProofRequest.getRequestUrl()
    setRequestUrl(url)

    const status = reclaimProofRequest.getStatusUrl()
    setStatusUrl(status)
    console.log('Status URL:', status)

    await reclaimProofRequest.startSession({
      onSuccess: (proofs) => {
        if (proofs && typeof proofs  === 'string') {
            // When using a custom callback url, the proof is returned to the callback url and we get a message instead of a proof
            console.log('SDK Message:', proofs)
            setProofs(proofs)
          } else if (proofs && typeof proofs !== 'string') {
            // When using the default callback url, we get a proof
            if (Array.isArray(proofs)) {
              // when using the cascading providers, providers having more than one proof will return an array of proofs
              console.log(JSON.stringify(proofs.map(p => p.claimData.context)))
            } else {
              console.log('Proof received:', proofs?.claimData.context)
            }
            setProofs(proofs)
          }
      },
      onFailure: (error) => {
        console.error('Verification failed', error)
      }
    })
  }

  return (
    <div className="App">
      <h1>Reclaim Protocol Demo</h1>
      <button onClick={handleCreateClaim}>Create Claim</button>
      {requestUrl && (
        <div>
          <h2>Scan this QR code to start the verification process:</h2>
          <QRCode value={requestUrl} />
        </div>
      )}
      {proofs && (
        <div>
          <h2>Verification Successful!</h2>
          <pre>{JSON.stringify(proofs, null, 2)}</pre>
        </div>
      )}
    </div>
  )
}

export default App

Step 4: Understanding the code

Let's break down what's happening in this code:

We initialize the Reclaim SDK with your application ID, secret, and provider ID. This happens once when the component mounts.
When the user clicks the "Create Claim" button, we:
- Generate a request URL using getRequestUrl(). This URL is used to create the QR code.
- Get the status URL using getStatusUrl(). This URL can be used to check the status of the claim process.
- Start a session with startSession(), which sets up callbacks for successful and failed verifications.
We display a QR code using the request URL. When a user scans this code, it starts the verification process.
The status URL is logged to the console. You can use this URL to check the status of the claim process programmatically.
When the verification is successful, we display the proof data on the page.

Step 5: New Streamlined Flow with Browser Extension Support

The Reclaim SDK now provides a simplified triggerReclaimFlow() method that automatically handles the verification process across different platforms and devices. This method intelligently chooses the best verification method based on the user's environment.

Using triggerReclaimFlow()

Replace the handleCreateClaim function in your React component with this simpler approach:

async function handleCreateClaim() {
  if (!reclaimProofRequest) {
    console.error('Reclaim Proof Request not initialized')
    return
  }

  try {
    // Start the verification process automatically
    await reclaimProofRequest.triggerReclaimFlow()

    // Listen for the verification results
    await reclaimProofRequest.startSession({
      onSuccess: (proofs) => {
        if (proofs && typeof proofs === 'string') {
          console.log('SDK Message:', proofs)
          setProofs(proofs)
        } else if (proofs && typeof proofs !== 'string') {
          if (Array.isArray(proofs)) {
            console.log(JSON.stringify(proofs.map(p => p.claimData.context)))
          } else {
            console.log('Proof received:', proofs?.claimData.context)
          }
          setProofs(proofs)
        }
      },
      onFailure: (error) => {
        console.error('Verification failed', error)
      }
    })
  } catch (error) {
    console.error('Error triggering Reclaim flow:', error)
  }
}

How triggerReclaimFlow() Works

The triggerReclaimFlow() method automatically detects the user's environment and chooses the optimal verification method:

On Desktop Browsers:

Browser Extension First: If the Reclaim browser extension is installed, it will use the extension for a seamless in-browser verification experience.
QR Code Fallback: If the extension is not available, it automatically displays a QR code modal for mobile scanning.

On Mobile Devices:

iOS Devices: Automatically redirects to the Reclaim App Clip for native iOS verification.
Android Devices: Automatically redirects to the Reclaim Instant App for native Android verification.

Browser Extension Support

The SDK now includes built-in support for the Reclaim browser extension, providing users with a seamless verification experience without leaving their current browser tab.

Features:

Automatic Detection: The SDK automatically detects if the Reclaim browser extension is installed
Seamless Integration: No additional setup required - the extension integration works out of the box
Fallback Support: If the extension is not available, the SDK gracefully falls back to QR code or mobile app flows

Manual Extension Detection:

You can also manually check if the browser extension is available:

const isExtensionAvailable = await reclaimProofRequest.isBrowserExtensionAvailable()
if (isExtensionAvailable) {
  console.log('Reclaim browser extension is installed')
} else {
  console.log('Browser extension not available, will use alternative flow')
}

Configuring Browser Extension Options:

You can customize the browser extension behavior during SDK initialization:

const proofRequest = await ReclaimProofRequest.init(
  APP_ID,
  APP_SECRET,
  PROVIDER_ID,
  {
    useBrowserExtension: true, // Enable/disable browser extension (default: true)
    extensionID: 'custom-extension-id', // Use custom extension ID if needed
    // ... other options
  }
)

When the QR code modal is displayed (fallback on desktop), you can customize its appearance:

// Set modal options before triggering the flow
reclaimProofRequest.setModalOptions({
  title: 'Custom Verification Title',
  description: 'Scan this QR code with your mobile device to verify your account',
  darkTheme: true, // Enable dark theme
  extensionUrl: 'https://custom-extension-url.com' // Custom extension download URL
})

await reclaimProofRequest.triggerReclaimFlow()

Benefits of the New Flow:

Platform Adaptive: Automatically chooses the best verification method for each platform
User-Friendly: Provides the most seamless experience possible for each user
Simplified Integration: Single method call handles all verification scenarios
Extension Support: Leverages browser extension for desktop users when available
Mobile Optimized: Native app experiences on mobile devices

Step 6: Run your application

Start your development server:

npm start

Your Reclaim SDK demo should now be running. Click the "Create Claim" button to generate a QR code. Scan this code to start the verification process.

Understanding the Claim Process

Creating a Claim: When you click "Create Claim", the SDK generates a unique request for verification.
QR Code: The QR code contains the request URL. When scanned, it initiates the verification process.
Status URL: This URL (logged to the console) can be used to check the status of the claim process. It's useful for tracking the progress of verification.
Verification: The onSuccess is called when verification is successful, providing the proof data. When using a custom callback url, the proof is returned to the callback url and we get a message instead of a proof.
Handling Failures: The onFailure is called if verification fails, allowing you to handle errors gracefully.

Advanced Configuration

The Reclaim SDK offers several advanced options to customize your integration:

Adding Context: You can add context to your proof request, which can be useful for providing additional information:
```
reclaimProofRequest.addContext('0x00000000000', 'Example context message')
```
Setting Parameters: If your provider requires specific parameters, you can set them like this:
```
reclaimProofRequest.setParams({ email: "test@example.com", userName: "testUser" })
```
Custom Redirect URL: Set a custom URL to redirect users after the verification process:
```
reclaimProofRequest.setRedirectUrl('https://example.com/redirect')
```
Custom Callback URL: Set a custom callback URL for your app which allows you to receive proofs and status updates on your callback URL: Pass in jsonProofResponse: true to receive the proof in JSON format: By default, the proof is returned as a url encoded string.
```
reclaimProofRequest.setAppCallbackUrl('https://example.com/callback', true)
```

Modal Customization for Desktop Users: Customize the appearance and behavior of the QR code modal shown to desktop users:

reclaimProofRequest.setModalOptions({
  title: 'Verify Your Account',
  description: 'Scan the QR code with your mobile device or install our browser extension',
  darkTheme: false, // Enable dark theme (default: false)
  extensionUrl: 'https://chrome.google.com/webstore/detail/reclaim' // Custom extension URL
})

Browser Extension Configuration: Configure browser extension behavior and detection:

// Check if browser extension is available
const isExtensionAvailable = await reclaimProofRequest.isBrowserExtensionAvailable()

// Trigger the verification flow with automatic platform detection
await reclaimProofRequest.triggerReclaimFlow()

// Initialize with browser extension options
const proofRequest = await ReclaimProofRequest.init(
  APP_ID,
  APP_SECRET,
  PROVIDER_ID,
  {
    useBrowserExtension: true, // Enable browser extension support (default: true)
    extensionID: 'custom-extension-id', // Custom extension identifier
    useAppClip: true, // Enable mobile app clips (default: true)
    log: true // Enable logging for debugging
  }
)

Platform-Specific Flow Control: The triggerReclaimFlow() method provides intelligent platform detection, but you can still use traditional methods for custom flows:

// Traditional approach with manual QR code handling
const requestUrl = await reclaimProofRequest.getRequestUrl()
// Display your own QR code implementation

// Or use the new streamlined approach
await reclaimProofRequest.triggerReclaimFlow()
// Automatically handles platform detection and optimal user experience

Exporting and Importing SDK Configuration: You can export the entire Reclaim SDK configuration as a JSON string and use it to initialize the SDK with the same configuration on a different service or backend:

// On the client-side or initial service
const configJson = reclaimProofRequest.toJsonString()
console.log('Exportable config:', configJson)

// Send this configJson to your backend or another service

// On the backend or different service
const importedRequest = ReclaimProofRequest.fromJsonString(configJson)
const requestUrl = await importedRequest.getRequestUrl()

This allows you to generate request URLs and other details from your backend or a different service while maintaining the same configuration.

Handling Proofs on Your Backend

For production applications, it's recommended to handle proofs on your backend:

Set a callback URL:

reclaimProofRequest.setCallbackUrl('https://your-backend.com/receive-proofs')

These options allow you to securely process proofs and status updates on your server.

Next Steps

Explore the Reclaim Protocol documentation for more advanced features and best practices for integrating the SDK into your production applications.

Happy coding with Reclaim Protocol!

Contributing to Our Project

We welcome contributions to our project! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.

Security Note

Always keep your Application Secret secure. Never expose it in client-side code or public repositories.

Code of Conduct

Please read and follow our Code of Conduct to ensure a positive and inclusive environment for all contributors.

Security

If you discover any security-related issues, please refer to our Security Policy for information on how to responsibly disclose vulnerabilities.

Contributor License Agreement

Before contributing to this project, please read and sign our Contributor License Agreement (CLA).

Indie Hackers

For Indie Hackers: Check out our guidelines and potential grant opportunities

License

This project is licensed under a custom license. By contributing to this project, you agree that your contributions will be licensed under its terms.

Thank you for your contributions!

Package detail

@reclaimprotocol/js-sdk

readme