Web SDK

This guide provides advanced options for the Reclaim Protocol SDK across multiple platforms. These options allow you to customize and enhance your integration for specific use cases.

Advanced Options

Reclaim SDKs provide a lot of flexibility to customize the verification process.

init()

The init method allows you to pass additional options to customize the SDK's behavior.

const proofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID',
  // optional fields
  { 
    useAppClip: true, // default: true
    log: true, // default: false
    useBrowserExtension: true, // default: true
    extensionID: 'custom-extension-id' // default: 'reclaim-extension'
  }
)

useAppClip (Default: true): This option enables the use of AppClip/Instant App for mobile users. Only should be set to true when building mobile apps.
log (Default: false): When set to true, enables detailed logging for debugging purposes.
useBrowserExtension (Default: true): This option enables the use of reclaim browser extension for desktop users. When extension is not installed, the SDK will fallback to QR code flow.
extensionID (Default: reclaim-extension): Unique extension identifier if using a custom reclaim browser extension.

setAppCallbackUrl()

The setAppCallbackUrl method allows you to specify a custom API endpoint where verification credentials(proofs) will be sent upon successful generation.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
// Make sure to set this before starting the verification session.
reclaimProofRequest.setAppCallbackUrl('https://your-api.com/receive-proofs') // your custom callback url here

Parameters for setAppCallbackUrl:

URL: The URL of the API endpoint where proofs will be sent.
jsonProofResponse (Optional) (Default: false): When set to false, the proof is returned as a url encoded message in the response. When set to true, the proof is returned as a JSON object in the response.

This is the recommended way to receive proofs directly on your endpoint. Make sure to use proper middleware to parse the proof object in the response. Eg. express.text({ type: '*/*', limit: '50mb' }) in express.js.

setRedirectUrl()

The setRedirectUrl method allows you to specify a custom URL where users will be redirected after the successful verification process.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
// Make sure to set this before starting the verification session.
reclaimProofRequest.setRedirectUrl('https://your-app.com/verification-complete')

Exporting and Importing SDK Configuration

The SDK provides methods to export and import the entire configuration as a JSON string. This allows you to use the same verification session across different platforms with all our SDKs.

// Export configuration
const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
const reclaimProofRequestConfig = reclaimProofRequest.toJsonString()
 
 
// On a different service or application import the configuration
const reclaimProofRequest = await ReclaimProofRequest.fromJsonString(reclaimProofRequestConfig)
 
// Start the verification session using either `getRequestUrl` or `triggerReclaimFlow`

verifyProof()

The SDK provides a method to verify the verification credentials(proofs) to ensure their authenticity. This is particularly useful when receiving proofs in your backend.

import { verifyProof } from 'reclaim-sdk'
 
// make sure proofObject is of type 'Proof' Object
const isValid = await verifyProof(proofObject)
if (isValid) {
  console.log('Proof is valid!')
} else {
  console.log('Invalid proof - signature verification failed')
}

addContext()

Use the addContext method to include any additional information in your verification credentials(proofs). This information will be included in the proof object under the context field.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
// Make sure to set this before starting the verification session.
reclaimProofRequest.addContext('0x1234567890abcdef', 'User registration proof')

contextId: Unique hex address identifier (string)
Context message: Additional information to be included in the proof object (string)

The contextId must be a valid hex address (starting with '0x' and containing only 0-9 and a-f).

setParams()

The setParams method lets you define specific conditions for proof generation, enabling selective triggering for verification sessions.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
// Make sure to set this before starting the verification session.
reclaimProofRequest.setParams({
  minConnections: '500', 
  industry: 'Technology'
})

Proof generation will fail if the specified parameters are not present on the provider website.

isBrowserExtensionAvailable()

The isBrowserExtensionAvailable method checks if any Reclaim browser extension is installed on the user's device.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
// Check if browser extension is available
const isExtensionAvailable = await reclaimProofRequest.isBrowserExtensionAvailable()
 
if (isExtensionAvailable) {
  console.log('Reclaim browser extension is installed')
  // Extension will be used automatically with triggerReclaimFlow()
} else {
  console.log('Browser extension not available, will use QR code flow')
}

setModalOptions()

You can use setModalOptions method to customize the modal appearance and behavior of the QR code modal popup (appears on desktop when browser extension is not installed). This is applicable only when using triggerReclaimFlow method.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
// Customize modal appearance before triggering flow
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' // Your extension download url
})
 
// Trigger the verification flow with custom modal
await reclaimProofRequest.triggerReclaimFlow()

Modal Options:

title: Custom title for the modal dialog
description: Custom description text shown to users
darkTheme (Default: false): Boolean to enable dark theme styling
extensionUrl: Custom URL to install/download the browser extension

Options to get various Session Details

The SDK provides methods to fetch additional details about the verification session.

getRequestUrl()

The getRequestUrl method returns the URL to start the verification session.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
const requestUrl = await reclaimProofRequest.getRequestUrl()

getSessionId()

The getSessionId method returns the unique identifier for the verification session.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
const sessionId = await reclaimProofRequest.getSessionId()

getStatusUrl()

The getStatusUrl method returns the URL to check the status of the verification session. You can use this URL to poll the status of the verification session.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
const statusUrl = await reclaimProofRequest.getStatusUrl()

getAppCallbackUrl()

The getAppCallbackUrl method returns the URL where the verification credentials(proofs) will be sent upon successful generation.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
const appCallbackUrl = await reclaimProofRequest.getAppCallbackUrl()

Understanding the Proof Structure

When using any Reclaim SDK (JavaScript, React Native, Flutter), a proof is generated and returned upon successful verification. This proof contains several key components that provide detailed information about the verification process. Below is a generic structure of a proof:

{
  "identifier": "unique_identifier_for_proof", // string
  "claimData": {
    "provider": "provider_type", // string
    "parameters": "verified_data_from_website", // stringified JSON object
    "owner": "owner_address", // string
    "timestampS": "timestamp_of_proof_generation", // int
    "context": "additional_context_information", // stringified JSON object
    "epoch": "epoch_number" // int
  },
  "signatures": [
    "signature_of_proof" // string
  ],
  "witnesses": [
    {
      "id": "witness_id", // string
      "url": "witness_url" // string
    }
  ],
  // publicData is optional and only available if provider supports it else it will be empty
  "publicData": {} // stringified JSON object
}

Web SDK

On this page