From 6311373c7f2db3829591ed3abd06fab09d5aedb5 Mon Sep 17 00:00:00 2001 From: madhavanmalolan Date: Tue, 11 Nov 2025 15:59:53 +0000 Subject: [PATCH 1/5] Adding websdk docs, simplifying js-sdk docs --- content/docs/flutter/meta.json | 2 +- content/docs/js-sdk/api-reference.mdx | 901 ---------------------- content/docs/js-sdk/generating-proof.mdx | 78 +- content/docs/js-sdk/installation.mdx | 6 +- content/docs/js-sdk/meta.json | 5 +- content/docs/js-sdk/preparing-request.mdx | 37 +- content/docs/js-sdk/verifying-proofs.mdx | 11 +- 7 files changed, 86 insertions(+), 954 deletions(-) delete mode 100644 content/docs/js-sdk/api-reference.mdx diff --git a/content/docs/flutter/meta.json b/content/docs/flutter/meta.json index 9f8a1cf..c96c211 100644 --- a/content/docs/flutter/meta.json +++ b/content/docs/flutter/meta.json @@ -1,4 +1,4 @@ { "title": "Flutter SDK", - "pages": ["installation", "usage"] + "pages": ["installation", "usage", "api-reference"] } \ No newline at end of file diff --git a/content/docs/js-sdk/api-reference.mdx b/content/docs/js-sdk/api-reference.mdx deleted file mode 100644 index 4cee384..0000000 --- a/content/docs/js-sdk/api-reference.mdx +++ /dev/null @@ -1,901 +0,0 @@ ---- -title: API Reference & Advanced Configuration -description: Complete API documentation and advanced configuration options for the Reclaim JavaScript SDK ---- - -## Overview - -This page documents all classes, methods, and types available in the Reclaim JavaScript SDK. - -## Installation - -```bash -npm install @reclaimprotocol/js-sdk -``` - -## Import - -```javascript -import { ReclaimProofRequest, verifyProof } from "@reclaimprotocol/js-sdk"; -``` - ---- - -## ReclaimProofRequest Class - -The main class for creating and managing proof requests. - -### Static Methods - -#### `ReclaimProofRequest.init(appId, appSecret, providerId)` - -Initialize a new proof request with your API credentials. - -**Parameters:** - -- `appId` (string, required): Your application ID from the Reclaim Developer Portal -- `appSecret` (string, required): Your application secret -- `providerId` (string, required): The provider ID to verify against - -**Returns:** `Promise` - -**Example:** - -```javascript -const reclaimProofRequest = await ReclaimProofRequest.init("your-app-id", "your-app-secret", "your-provider-id"); -``` - -**Security**: Initialize from backend only in production. Never expose `appSecret` in client-side code. - -#### `ReclaimProofRequest.fromJsonString(configString)` - -Reconstruct a proof request from a JSON configuration string (typically generated on the backend). - -**Parameters:** - -- `configString` (string, required): JSON string from `toJsonString()` - -**Returns:** `Promise` - -**Example:** - -```javascript -// Backend generates config -const config = reclaimProofRequest.toJsonString(); - -// Frontend reconstructs from config -const reconstructed = await ReclaimProofRequest.fromJsonString(config); -``` - ---- - -### Instance Methods - -#### `getRequestUrl()` - -Generate a verification request URL for manual display (QR codes, links, etc.). - -**Returns:** `Promise` - The verification request URL - -**Example:** - -```javascript -const requestUrl = await reclaimProofRequest.getRequestUrl(); -console.log("Verification URL:", requestUrl); -// Display as QR code or clickable link -``` - -#### `getStatusUrl()` - -Get the status polling URL for checking verification progress. - -**Returns:** `string` - The status URL - -**Example:** - -```javascript -const statusUrl = reclaimProofRequest.getStatusUrl(); -console.log("Status URL:", statusUrl); -``` - -#### `triggerReclaimFlow(options?)` - -Automatically trigger the optimal verification flow based on user's platform. Shows QR code modal on desktop, redirects to App Clip/Instant App on mobile, or uses browser extension if available. - -**Parameters:** - -- `options` (object, optional): Configuration options for the flow - -**Options Object:** - -- `theme` (string): `'light'` or `'dark'` - Modal theme (default: `'light'`) -- `modalTitle` (string): Custom title for the QR modal -- `modalSubtitle` (string): Custom subtitle for the QR modal -- `autoCloseModal` (boolean): Auto-close modal after successful verification (default: `false`) -- `autoCloseDelay` (number): Delay in ms before auto-closing (default: `3000`) -- `showExtensionPrompt` (boolean): Show browser extension install prompt if not installed (default: `true`) -- `onModalOpen` (function): Callback when modal opens -- `onModalClose` (function): Callback when modal closes - -**Returns:** `Promise` - -**Example:** - -```javascript -await reclaimProofRequest.triggerReclaimFlow({ - theme: "dark", - modalTitle: "Verify Your Account", - autoCloseModal: true, - autoCloseDelay: 2000, - onModalOpen: () => console.log("Modal opened"), - onModalClose: () => console.log("Modal closed"), -}); -``` - -#### `startSession(callbacks)` - -Start listening for proof submissions. Must be called after generating request URL or triggering flow. - -**Parameters:** - -- `callbacks` (object, required): Callback functions - -**Callbacks Object:** - -- `onSuccess` (function, required): Called when proof is successfully generated - - Receives: `(proofs: Proof) => void` -- `onError` (function, required): Called when verification fails - - Receives: `(error: Error) => void` - -**Returns:** `Promise` - -**Example:** - -```javascript -await reclaimProofRequest.startSession({ - onSuccess: (proofs) => { - console.log("Verification successful!", proofs); - // Process the proofs - }, - onError: (error) => { - console.error("Verification failed:", error); - // Handle error - }, -}); -``` - -#### `setAppCallbackUrl(url)` - -Set a callback URL where Reclaim will send proofs after verification (for backend processing). - -**Parameters:** - -- `url` (string, required): Your backend callback URL (must be publicly accessible) - -**Returns:** `void` - -**Example:** - -```javascript -reclaimProofRequest.setAppCallbackUrl("https://yourapp.com/api/reclaim/callback"); -``` - -#### `toJsonString()` - -Serialize the proof request to a JSON string (safe to send to frontend, excludes secrets). - -**Returns:** `string` - JSON configuration string - -**Example:** - -```javascript -// Backend -const config = reclaimProofRequest.toJsonString(); -res.json({ reclaimProofRequestConfig: config }); - -// Frontend receives and reconstructs -const reconstructed = await ReclaimProofRequest.fromJsonString(config); -``` - -#### `isBrowserExtensionAvailable()` - -Check if the Reclaim browser extension is installed and available. - -**Returns:** `Promise` - -**Example:** - -```javascript -const hasExtension = await reclaimProofRequest.isBrowserExtensionAvailable(); - -if (hasExtension) { - console.log("Extension available - will use in-browser verification"); -} else { - console.log("No extension - will show QR code"); -} -``` - ---- - -## Advanced Configuration - - -**Customization Options** - -The SDK provides extensive customization options for the verification flow, UI appearance, and behavior. Jump to any section: - -- [🎨 Modal Customization](#modal-customization) - Configure QR modal appearance and behavior -- [⚙️ Custom Parameters](#custom-parameters) - Add metadata with `setParams()` -- [📝 Context Addition](#context-addition) - Add signed context with `addContext()` -- [🧩 Browser Extension](#browser-extension-configuration) - Configure extension behavior -- [🔗 Callback URLs](#callback-urls) - Set backend callback endpoints -- [🔀 Custom Redirects](#custom-redirects) - Configure post-verification redirects -- [🎯 Session Callbacks](#session-callbacks) - Handle `onSuccess`/`onFailure` events -- [💡 Complete Example](#complete-configuration-example) - See all features together - - - ---- - -### 🎨 Modal Customization - -#### `setModalOptions(options)` - -Configure the QR code modal appearance, behavior, and callbacks. - -**Parameters:** - -- `options` (object, required): Configuration object for the modal - -**Options Object:** - -- `darkTheme` (boolean): Enable dark mode styling (default: `false`) -- `title` (string): Custom modal title -- `description` (string): Custom modal description text -- `modalPopupTimer` (number): Auto-close timer in minutes (0 = no auto-close) -- `showExtensionInstallButton` (boolean): Show browser extension install prompt -- `extensionUrl` (string): Custom extension URL for install button -- `onClose` (function): Callback function when modal is closed by user - -**Returns:** `void` - -**Example:** - -```javascript -reclaimProofRequest.setModalOptions({ - // Theme - darkTheme: true, - - // Text customization - title: "Verify Your Account", - description: "Scan this QR code with your mobile device to continue", - - // Behavior - modalPopupTimer: 5, // Auto-close after 5 minutes of inactivity - - // Browser extension - showExtensionInstallButton: true, - extensionUrl: "https://chrome.google.com/webstore/...", - - // Callbacks - onClose: () => { - console.log("User closed the verification modal"); - // Handle modal closure (e.g., show alternative flow) - }, -}); -``` - -**Use Cases:** - -- Match your app's theme (light/dark mode) -- Provide context-specific instructions -- Handle user abandonment with `onClose` callback -- Promote browser extension installation - ---- - -### ⚙️ Custom Parameters - -#### `setParams(params)` - -Add custom key-value parameters to the proof request. These parameters will be included in the verified proof and can be used for application-specific metadata. - -**Parameters:** - -- `params` (object, required): Key-value pairs of custom data - -**Returns:** `void` - -**Example:** - -```javascript -reclaimProofRequest.setParams({ - userId: "user_12345", - action: "account_verification", - tier: "premium", - timestamp: Date.now(), - sessionId: "abc-def-ghi", -}); -``` - -**Access in Proof:** - -```javascript -// The parameters are included in the proof -await reclaimProofRequest.startSession({ - onSuccess: (proofs) => { - const parameters = JSON.parse(proofs.claimData.parameters); - }, -}); -``` - ---- - -### 📝 Context Addition - -#### `addContext(address, message)` - -Add custom context or metadata to the proof request. Context is signed and included in the cryptographic proof. - -**Parameters:** - -- `address` (string, required): Context identifier (e.g., wallet address, user ID) -- `message` (string, required): Context message or metadata - -**Returns:** `void` - -**Example:** - -```javascript -// Add wallet address context -reclaimProofRequest.addContext("0x1234567890abcdef1234567890abcdef12345678", "Verification for DeFi platform access"); - -// Or add any custom context -reclaimProofRequest.addContext("user_id_12345", "Email verification for premium tier upgrade"); -``` - -**Access in Proof:** - -```javascript -await reclaimProofRequest.startSession({ - onSuccess: (proofs) => { - const context = JSON.parse(proofs.claimData.context); - console.log("Context:", context); - }, -}); -``` - -**Use Cases:** - -- Link verification to blockchain addresses -- Add tamper-proof metadata -- Include application-specific identifiers -- Create auditable verification records - ---- - -### 🧩 Browser Extension Configuration - -#### Extension Initialization Options - -Configure browser extension behavior when initializing the proof request. - -**Parameters (in `init()` fourth argument):** - -- `useBrowserExtension` (boolean): Enable/disable extension detection (default: `true`) -- `extensionID` (string): Custom browser extension identifier - -**Example:** - -```javascript -// Enable extension with custom ID -const reclaimProofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID, { - useBrowserExtension: true, - extensionID: "your-custom-extension-id", -}); - -// Disable extension (always use QR/mobile flow) -const reclaimProofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID, { - useBrowserExtension: false, -}); -``` - -#### Check Extension Availability - -Use `isBrowserExtensionAvailable()` to conditionally render UI based on extension presence: - -**Example:** - -```javascript -const hasExtension = await reclaimProofRequest.isBrowserExtensionAvailable(); - -if (hasExtension) { - // Show "Verify with Extension" button - showExtensionButton(); -} else { - // Show "Scan QR Code" instructions - showQRCodeInstructions(); -} -``` - -**Use Cases:** - -- Provide different UI for extension vs non-extension users -- Show extension install prompts strategically -- Optimize verification flow based on capabilities - ---- - -### 🔗 Callback URLs - -#### `setAppCallbackUrl(url)` - -Set a backend callback URL where Reclaim Protocol will POST proofs directly after verification. This enables secure backend proof processing without relying on frontend delivery. - -**Parameters:** - -- `url` (string, required): Your publicly accessible backend endpoint - -**Returns:** `void` - -**Example:** - -```javascript -// Backend receives proofs directly from Reclaim -reclaimProofRequest.setAppCallbackUrl("https://yourapp.com/api/reclaim/callback"); - -// Backend endpoint -app.post("/api/reclaim/callback", async (req, res) => { - const proof = req.body; // Proof sent directly by Reclaim - - // Verify proof - const isValid = await verifyProof(proof); - - if (isValid) { - // Process verified data - await updateUserRecord(proof); - } - - res.sendStatus(200); // Acknowledge receipt -}); -``` - -**Requirements:** - -- URL must be publicly accessible (not localhost) -- Endpoint should return 200 OK response -- Implement proof verification on backend - -**Benefits:** - -- ✅ Proofs delivered directly to your backend (more secure) -- ✅ No dependency on frontend proof handling -- ✅ Backend can process async without user waiting -- ✅ Automatic retry on delivery failure - ---- - -### 🔀 Custom Redirects - -#### `setRedirectUrl(url)` - -Set a custom redirect URL where users will be sent after completing verification on mobile (App Clip, Instant App, deep link). - -**Parameters:** - -- `url` (string, required): Your app's redirect destination - -**Returns:** `void` - -**Example:** - -```javascript -// Redirect to success page after verification -reclaimProofRequest.setRedirectUrl("https://yourapp.com/verification/success"); - -// Or deep link back to your mobile app -reclaimProofRequest.setRedirectUrl("yourapp://verification-complete"); -``` - -**Use Cases:** - -- Guide users back to your app after mobile verification -- Show custom success/thank you pages -- Deep link into specific app sections -- Track verification completion - ---- - -### 🎯 Session Callbacks - -#### Enhanced `startSession()` Callbacks - -The `startSession()` method provides detailed callbacks for handling verification results. - -**Callback Signatures:** - -```typescript -interface SessionCallbacks { - onSuccess: (proofs: Proof | string) => void; - onFailure: (error: Error) => void; -} -``` - -**Detailed Example:** - -```javascript -await reclaimProofRequest.startSession({ - onSuccess: (proofs) => { - console.log('✅ Verification successful!'); - - // Proofs can be either object or string message - if (typeof proofs === 'string') { - console.log('Message:', proofs); - } else { - console.log('Proof ID:', proofs.identifier); - console.log('Provider:', proofs.claimData.provider); - console.log('Timestamp:', new Date(proofs.timestampS * 1000)); - - // Extract verified data - const parameters = JSON.parse(proofs.claimData.parameters); - console.log('Verified data:', parameters); - - // Send to backend for processing - await fetch('/api/verify', { - method: 'POST', - body: JSON.stringify(proofs), - headers: { 'Content-Type': 'application/json' } - }); - } - }, - - onFailure: (error) => { - console.error('❌ Verification failed:', error); - - // Handle specific error types - if (error.message.includes('timeout')) { - showTimeoutMessage(); - } else if (error.message.includes('cancelled')) { - showCancelledMessage(); - } else { - showGenericErrorMessage(); - } - - // Log for debugging - logVerificationFailure(error); - } -}); -``` - -**Error Scenarios Handled:** - -- User cancels verification -- Verification timeout -- Network connectivity issues -- Invalid provider configuration -- Backend callback failures - ---- - -### 💡 Complete Configuration Example - -Here's a comprehensive example using multiple advanced features: - -```javascript -// Initialize with extension config -const reclaimProofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID, { - useBrowserExtension: true, - extensionID: "custom-extension-id", -}); - -// Set backend callback for proof delivery -reclaimProofRequest.setAppCallbackUrl("https://yourapp.com/api/reclaim/callback"); - -// Add custom parameters -reclaimProofRequest.setParams({ - userId: "user_12345", - action: "premium_verification", - timestamp: Date.now(), -}); - -// Add context -reclaimProofRequest.addContext("0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2", "DeFi platform verification"); - -// Set custom redirect -reclaimProofRequest.setRedirectUrl("https://yourapp.com/verification/complete"); - -// Configure modal appearance -reclaimProofRequest.setModalOptions({ - darkTheme: true, - title: "Verify Your Premium Account", - description: "Scan with your mobile device", - modalPopupTimer: 10, - showExtensionInstallButton: true, - onClose: () => { - console.log("Modal closed by user"); - trackEvent("verification_abandoned"); - }, -}); - -// Check for extension -const hasExtension = await reclaimProofRequest.isBrowserExtensionAvailable(); -console.log("Extension available:", hasExtension); - -// Trigger verification flow -await reclaimProofRequest.triggerReclaimFlow(); - -// Handle results -await reclaimProofRequest.startSession({ - onSuccess: async (proofs) => { - console.log("Verification successful!"); - await processProof(proofs); - }, - onFailure: (error) => { - console.error("Verification failed:", error); - handleVerificationError(error); - }, -}); -``` - ---- - -## Standalone Functions - -### `verifyProof(proof)` - -Cryptographically verify a proof received from Reclaim Protocol. - -**Parameters:** - -- `proof` (Proof object, required): The proof to verify - -**Returns:** `Promise` - `true` if proof is valid, `false` otherwise - -**Example:** - -```javascript -import { verifyProof } from "@reclaimprotocol/js-sdk"; - -app.post("/api/reclaim/callback", async (req, res) => { - const proof = parseProof(req.body); - - const isValid = await verifyProof(proof); - - if (isValid) { - console.log("✅ Proof is valid"); - // Process verified data - } else { - console.log("❌ Proof verification failed"); - } - - res.sendStatus(200); -}); -``` - - - **Best Practice**: Always verify proofs on your backend before trusting the data. Never rely solely on client-side verification. - - ---- - -## Type Definitions - -### Proof Object - -The proof object received after successful verification: - -```typescript -interface Proof { - identifier: string; // Unique proof identifier - claimData: ClaimData; // Claim details - signatures: string[]; // Cryptographic signatures - witnesses: Witness[]; // Witness attestations - timestampS: number; // Unix timestamp in seconds -} - -interface ClaimData { - provider: string; // Provider name (e.g., "google") - parameters: string; // JSON string of provider parameters - context: string; // JSON string of context data -} - -interface Witness { - address: string; // Witness address - signature: string; // Witness signature -} -``` - -**Example Proof:** - -```json -{ - "identifier": "0x1234567890abcdef...", - "claimData": { - "provider": "google", - "parameters": "{\"email\":\"user@example.com\"}", - "context": "{\"extractedParameters\":{\"providerName\":\"google\"}}" - }, - "signatures": ["0xabcdef..."], - "witnesses": [ - { - "address": "0x789...", - "signature": "0xdef..." - } - ], - "timestampS": 1234567890 -} -``` - -### Accessing Proof Data - -```javascript -// Extract provider name -const context = JSON.parse(proof.claimData.context); -const providerName = context.extractedParameters.providerName; - -// Extract parameters (varies by provider) -const parameters = JSON.parse(proof.claimData.parameters); - -// Get verification timestamp -const verifiedAt = new Date(proof.timestampS * 1000); -``` - ---- - -## Error Handling - -### Common Errors - -#### Invalid Credentials Error - -```javascript -try { - await ReclaimProofRequest.init(appId, appSecret, providerId); -} catch (error) { - if (error.message.includes("Invalid credentials")) { - console.error("Check your APP_ID and APP_SECRET"); - } -} -``` - -#### Provider Not Found Error - -```javascript -try { - await ReclaimProofRequest.init(appId, appSecret, providerId); -} catch (error) { - if (error.message.includes("Provider")) { - console.error("Verify your PROVIDER_ID is correct"); - } -} -``` - -#### Verification Timeout - -```javascript -await reclaimProofRequest.startSession({ - onError: (error) => { - if (error.message.includes("timeout")) { - console.error("Verification timed out - user may have abandoned flow"); - } - }, -}); -``` - ---- - -## Usage Patterns - -### Pattern 1: Backend Initialization (Recommended) - -```javascript -// Backend -app.get("/api/reclaim/config", async (req, res) => { - const reclaimProofRequest = await ReclaimProofRequest.init( - process.env.RECLAIM_APP_ID, - process.env.RECLAIM_APP_SECRET, - process.env.RECLAIM_PROVIDER_ID - ); - - reclaimProofRequest.setAppCallbackUrl(`${BASE_URL}/api/reclaim/callback`); - const config = reclaimProofRequest.toJsonString(); - - res.json({ reclaimProofRequestConfig: config }); -}); - -// Frontend -const response = await fetch("/api/reclaim/config"); -const { reclaimProofRequestConfig } = await response.json(); - -const reclaimProofRequest = await ReclaimProofRequest.fromJsonString(reclaimProofRequestConfig); - -await reclaimProofRequest.triggerReclaimFlow(); -await reclaimProofRequest.startSession({ onSuccess, onError }); -``` - -### Pattern 2: Client-Side Only (Development Only) - -```javascript -// ⚠️ Not for production - exposes APP_SECRET -const reclaimProofRequest = await ReclaimProofRequest.init( - "your-app-id", - "your-app-secret", // Exposed! - "your-provider-id" -); - -await reclaimProofRequest.triggerReclaimFlow(); - -await reclaimProofRequest.startSession({ - onSuccess: (proofs) => console.log("Success:", proofs), - onError: (error) => console.error("Error:", error), -}); -``` - -### Pattern 3: Manual URL Display - -```javascript -const reclaimProofRequest = await ReclaimProofRequest.fromJsonString(config); -const requestUrl = await reclaimProofRequest.getRequestUrl(); - -// Display QR code -renderQRCode(requestUrl); - -// Start listening -await reclaimProofRequest.startSession({ onSuccess, onError }); -``` - ---- - -## Platform Detection - -The SDK automatically detects the user's platform and provides the best experience: - -| Platform | Detection Method | Verification Flow | -| ---------------------- | ------------------ | -------------------------- | -| Desktop Chrome/Edge | User agent | QR code modal or extension | -| Desktop Safari/Firefox | User agent | QR code modal | -| iOS Safari | User agent + touch | App Clip redirect | -| Android Chrome | User agent + touch | Instant App redirect | -| Mobile browsers | Touch capability | Deep link or QR | - ---- - -## Browser Compatibility - -- ✅ Chrome 93+ -- ✅ Edge 93+ -- ✅ Safari 14+ -- ✅ Firefox 90+ -- ✅ Opera 79+ -- ✅ Mobile browsers (iOS Safari 14+, Chrome Mobile) - ---- - -## TypeScript Support - -The SDK includes TypeScript definitions out of the box: - -```typescript -import { ReclaimProofRequest, Proof } from "@reclaimprotocol/js-sdk"; - -const reclaimProofRequest: ReclaimProofRequest = await ReclaimProofRequest.init(appId, appSecret, providerId); - -const handleSuccess = (proofs: Proof): void => { - console.log("Proof received:", proofs.identifier); -}; -``` - ---- - -## Next Steps - -- **[Installation →](/js-sdk/installation)** - Install the SDK -- **[Quickstart →](/js-sdk/quickstart)** - Quick integration guide -- **[Recommended Setup →](/js-sdk/recommended-setup)** - Production-ready setup -- **[Troubleshooting →](/js-sdk/troubleshooting)** - Common issues and solutions - -## Need Help? - -- 💬 [Community Discord](https://discord.gg/reclaim) -- 🐛 [GitHub Issues](https://github.com/reclaimprotocol/reclaim-js-sdk/issues) -- 📚 [GitHub Repository](https://github.com/reclaimprotocol/reclaim-js-sdk) diff --git a/content/docs/js-sdk/generating-proof.mdx b/content/docs/js-sdk/generating-proof.mdx index e189d14..5e0cc21 100644 --- a/content/docs/js-sdk/generating-proof.mdx +++ b/content/docs/js-sdk/generating-proof.mdx @@ -5,30 +5,14 @@ description: Initiate the proof request to the user on the frontend # What is initiating a proof request? In the [previous section](/preparing-request), you just built the request containing the information on what proof you want the user to generate. -Now it is turn to actually ask the user to generate the proof. +Now it is turn to actually ask the user to generate the proof. Depending on the user's device, browser and operating system, the SDK will pick the most seamless verification mechanism available for that user. -There are many ways the user can generate a proof. +Available options : +- [iOS AppClip](https://blog.reclaimprotocol.org/posts/appclip-and-instantapp) and [Android Instant Apps](https://blog.reclaimprotocol.org/posts/moving-beyond-google-play-instant) +- [iOS App](https://apps.apple.com/be/app/reclaim-verifier/id6503247508) and [Android App](https://play.google.com/store/apps/details?id=org.reclaimprotocol.app&hl=en_US) +- [Browser Extension](https://docs.reclaimprotocol.org/browser-extension) +- [Remote browser](preparing-request#forcing-remote-browser-use) -## User is on a desktop -Till January 31 2026, the proofs can generate a proof only using a mobile device. If the user opens your webapp on a desktop, they should be presented a QR code that they can scan with their iOS or Android device. Once they scan this QR code, they will be directed through the flow as mentioned below. - -## User is on a mobile device -- If the user is on iOS - - if the user is on iOS 14+ : they will be shown the Reclaim Protocol AppClip, where they can generate the proof without installing anything. - - if the user is on iOS 13 or below: they will be taken to the AppStore to install the Reclaim Protocol App, where they will now be able to generate the proof. -- If the user is on Android - - Until December 1 2025 : they will be shown the Reclaim Protocol Instant App, where they can generate the proof without installing anything. - - After December 1 2025 : they will be taken to the PlayStore to install the Reclaim Protocol App, where they will be able to generate the proof. - -## User is on a desktop with Reclaim Protocol Browser Extension installed -If the user has the browser extension installed, they needn't scan the QR code - they can generate the proof directly in the Reclaim Protocol (or any partner) Browser Extension. - -## January 31 2026 onwards -On January 31, the Reclaim Protocol Embedded SDK is marked for public release. From this date, the users will not have to change devices or install any software to generate proofs. You can [request for early access](https://t.me/protocolreclaim) for the EmbeddedSDK. - -## So many conditions?! -There are many combinations of device, browser and OS that are possible - leading to a lot of if else conditions. -The Reclaim Protocol JS SDK will handle all the cases for you, so you need to call only one function and it will automatically upgrade to the most seamless available flow! # Quickstart ## Get the `proofRequestObject` from the backend @@ -54,13 +38,12 @@ This step will take care of all the conditions for you - and use the most seamle ## Listen for the proof generation process You can receive callbacks when the proof generation process completes or fails so that you can update your UI accordingly for the user's next steps. -onSuccess is called after the user has generated the proof and the proof has been uploaded to the callback endpoint which we will define in the next section - [verifying the proofs](/js-sdk/verifying-proofs). - -Note : onSuccess means the proof has been successfully uploaded, but doesn't mean it's been verified. For verifying, please see the next section - [verifying the proofs](/js-sdk/verifying-proofs). +onSuccess is called after the user has generated the proof, but you must [verify the proofs on the backend](/js-sdk/verifying-proofs) to be sure that the user wasn't being malicious. ```javascript await reclaimProofRequest.startSession({ onSuccess: (proofs) => { + // upload proofs to your backend and verify // ... continue business logic }, onError: (err) => { @@ -96,8 +79,9 @@ export function useReclaim() { await reclaimProofRequest.triggerReclaimFlow(); await reclaimProofRequest.startSession({ - onSuccess: (proofs) => { + onSuccess: async (proofs) => { setProofs(proofs); + await uploadProofs(proofs); setIsLoading(false); }, onError: (err) => { @@ -114,7 +98,7 @@ export function useReclaim() { return { proofs, isLoading, error, startVerification }; } ``` -# More options +# Advance options ## Implement your own UI If you don't want the SDK to take care of the navigations or you want to implement your own UI, you can do so. @@ -152,6 +136,46 @@ reclaimProofRequest.setRedirectUrl("https://yourapp.com/verification/success"); reclaimProofRequest.setRedirectUrl("yourapp://verification-complete"); ``` +## Showing Progress + +You can poll the progress of the proof generation process and update the UI accordingly, especially if you are not using the `startSession` method. + +```javascript +const statusUrl = reclaimProofRequest.getStatusUrl(); +``` + +## Customize UI + +Automatically trigger the optimal verification flow based on user's platform. Shows QR code modal on desktop, redirects to App Clip/Instant App on mobile, or uses browser extension if available. The default UI can be customized : + + + +**Options Object:** + +- `theme` (string): `'light'` or `'dark'` - Modal theme (default: `'light'`) +- `modalTitle` (string): Custom title for the QR modal +- `modalSubtitle` (string): Custom subtitle for the QR modal +- `autoCloseModal` (boolean): Auto-close modal after successful verification (default: `false`) +- `autoCloseDelay` (number): Delay in ms before auto-closing (default: `3000`) +- `showExtensionPrompt` (boolean): Show browser extension install prompt if not installed (default: `true`) +- `onModalOpen` (function): Callback when modal opens +- `onModalClose` (function): Callback when modal closes + +``` +reclaimProofRequest.triggerReclaimFlow(options) +``` + +## Passing variables through the proof object + +You can add custom key-value parameters to the proof request. These parameters will be included in the verified proof and can be used for application-specific metadata. However, the parameters are not cryptographically bound to the proof. If they are edited by a malicious user, there is no way to detect. So we recommend putting only metadata in parameters that are not strictly mission critical. This is useful to pass variables into the proof object instead of having to maintain state separately. For mission critical variables that should not be possible for the user to edit, please refer [`setContext`](preparing-request#set-context) instead. + +``` +reclaimProofRequest.setParams({ + action: "account_verification", + timestamp: Date.now(), + ... +}); +``` diff --git a/content/docs/js-sdk/installation.mdx b/content/docs/js-sdk/installation.mdx index 1f3557c..f039ac3 100644 --- a/content/docs/js-sdk/installation.mdx +++ b/content/docs/js-sdk/installation.mdx @@ -28,9 +28,9 @@ pnpm add @reclaimprotocol/js-sdk # Next steps There are 3 steps in integrating the JavaScript SDK -1. Preparing the proof request on the backend -2. Asking the user to generate the proof on the frontend -3. Uploading the proof to the backend and verifying it +1. [Preparing](preparing-request) the proof request on the backend +2. Asking the user to [generate](generating-proof) the proof on the frontend +3. Uploading the proof to the backend and [verifying](verifying-proof) it This guide will walk you through each of these three steps. diff --git a/content/docs/js-sdk/meta.json b/content/docs/js-sdk/meta.json index 9f15f44..9229a33 100644 --- a/content/docs/js-sdk/meta.json +++ b/content/docs/js-sdk/meta.json @@ -1,10 +1,9 @@ { - "title": "JavaScript SDK", + "title": "NextJS/React SDK", "pages": [ "installation", "preparing-request", "generating-proof", - "verifying-proofs", - "api-reference" + "verifying-proofs" ] } diff --git a/content/docs/js-sdk/preparing-request.mdx b/content/docs/js-sdk/preparing-request.mdx index 6e9ae6f..f6f83f9 100644 --- a/content/docs/js-sdk/preparing-request.mdx +++ b/content/docs/js-sdk/preparing-request.mdx @@ -6,18 +6,18 @@ description: Create a request for a proof generation on the backend # What is a proof request? You need to prepare a proof request that will then be presented to the user on the frontend. This proof request, most importantly, tells the user -1. With which application they will be sharing the proof +1. With which application they will be sharing the data with 2. What is it that they need to prove to the said application # Quickstart -This is the simplest version of creating a proof request. For more advanced options, see the next section - More Options. +This is the simplest version of creating a proof request. ## Import the library ```javascript import { ReclaimProofRequest } from '@reclaimprotocol/js-sdk'; ``` -## Create an endpoint to build the `Proof Request` +## Create an endpoint to build the `Proof Request` on your backend ```javascript const reclaimProofRequest = await ReclaimProofRequest.init( 'APP_ID', @@ -28,13 +28,6 @@ const reclaimProofRequest = await ReclaimProofRequest.init( - You can get the `APP_ID` and `APP_SECRET` using [this guide](/api-key) - The `PROVIDER_ID` is the proof you want the user to generate. You can see all the [available providers here](https://dev.reclaimprotocol.org/explore). -## Set a callback url -The callback url is important. Once the proof is generated, this will be the endpoint to which the proof will be uploaded after the proof is generated by the user. This would be where you will update the state of the user to verified - once the proof is uploaded and verified. We will look at the implementation in the [verify the proof](/js-sdk/verify-proof) section. - -You will need to set the `callbackUrl` when building the proof request. -```javascript -reclaimProofRequest.setAppCallbackUrl('https://yourdomain.com/api/reclaimprotocol-callback') -``` ## Send back the proof request object to the frontend ```javascript const proofRequestObject = reclaimProofRequest.toJsonString(); @@ -57,9 +50,6 @@ export async function GET(request) { providerId, ); - const baseUrl = process.env.NEXT_PUBLIC_BASE_URL; - reclaimProofRequest.setAppCallbackUrl(`${baseUrl}/api/reclaimprotocol-callback`); - // Convert to JSON string (safe for frontend) const proofRequestObject = reclaimProofRequest.toJsonString(); @@ -71,7 +61,21 @@ export async function GET(request) { ``` -# More Options +# Advance Options +## Forcing Remote Browser use + + Remote Browser use is available only for users on a premium enterprise plan. Please [contact support](https://t.me/protocolreclaim) for more details. + +``` +proofRequestOptions = { + ..., //other options, if any + useAppClip: false, + customSharePageUrl: 'CONTACT_SUPPORT_FOR_URL' +} + +const proofRequest = await ReclaimProofRequest.init(appId, appSecret, providerId, proofRequestOptions); +``` + ## Set Context You can set context to the proof request that helps identify the request when you receive it back in the callback. ``` @@ -80,3 +84,8 @@ reclaimProofRequest.setContext('address', 'message') - `address` : this is usually a unique identifier for the user. This could be an email address, a wallet address, or just a session id - `message` : this is an open field where you can add any other information that you want passed around from the build request to the callback endpoint. You can stringify jsons here for convenience. +## Set Callback +``` +reclaimProofRequest.setAppCallbackUrl(url) +``` +Set a backend callback URL where Reclaim Protocol will POST proofs directly after verification. This enables secure backend proof processing without relying on frontend to upload the proof. diff --git a/content/docs/js-sdk/verifying-proofs.mdx b/content/docs/js-sdk/verifying-proofs.mdx index 0c0c245..ef5c72e 100644 --- a/content/docs/js-sdk/verifying-proofs.mdx +++ b/content/docs/js-sdk/verifying-proofs.mdx @@ -4,20 +4,18 @@ description: Critical step to make sure user is not trying to defraud your app --- # Why do I need to verify, when the proof has already been generated? -The [proof generation](/js-sdk/generating-proof) is a client side operation to protect the privacy and security of the user. Once the proof is generate, the proof is uploaded to the backend. A malicious user may generate a proof (or not) on their client side - and choose to upload an arbitrary json object to your backend. If you don't verify the proof, the arbitrary JSON object and the actual Prooj JSON object will be indistinguishable. +The [proof generation](/js-sdk/generating-proof) is a client side operation to protect the privacy and security of the user. However, if the user is malicious and you don't verify the proof on the backend, the user could use browser injections to trick your webapp to call `onSuccess` callback even without creating a valid proof. So, you must force your frontend to upload the proof generated or claimed to have been generated and verify them before you take the user to the next step in your business logic. -Verifying proofs is a very simple light weight operation. You can think of it as verifying the digital signatures to make sure the data is tamper proof. +Verifying proofs is a very simple light weight operation. You can think of it as verifying the digital signatures to make sure the data is tamper resistant. # Quickstart ## Setup the callback endpoint -This should be the same callback endpoint that was set when [building the proof request](preparing-request). +This should be the endpoint that will be called by your [`onSuccess` callback](generating-proof). This endpoint should be of type `POST`. ## Decode the proof object -The proof object is a URIEncoded JSON object. So, you need to decode it and then parse it. ```javascript -const decodedBody = decodeURIComponent(req.body); const proofs = JSON.parse(decodedBody); ``` @@ -44,6 +42,9 @@ const { extractedParameters } = JSON.parse(proofs[i].context); ## Sanity Check `TODO` +## Sample implementation in Next.js +`TODO` + # Structure of proofs ```json { From c25a9c077d5e638836c92c8bc357aeefa6559452 Mon Sep 17 00:00:00 2001 From: madhavanmalolan Date: Thu, 13 Nov 2025 00:33:38 +0000 Subject: [PATCH 2/5] fixing setParams doc --- content/docs/js-sdk/generating-proof.mdx | 16 ---------------- content/docs/js-sdk/preparing-request.mdx | 14 +++++++++++++- content/docs/js-sdk/verifying-proofs.mdx | 2 +- 3 files changed, 14 insertions(+), 18 deletions(-) diff --git a/content/docs/js-sdk/generating-proof.mdx b/content/docs/js-sdk/generating-proof.mdx index 5e0cc21..50909c6 100644 --- a/content/docs/js-sdk/generating-proof.mdx +++ b/content/docs/js-sdk/generating-proof.mdx @@ -164,19 +164,3 @@ Automatically trigger the optimal verification flow based on user's platform. Sh ``` reclaimProofRequest.triggerReclaimFlow(options) ``` - -## Passing variables through the proof object - -You can add custom key-value parameters to the proof request. These parameters will be included in the verified proof and can be used for application-specific metadata. However, the parameters are not cryptographically bound to the proof. If they are edited by a malicious user, there is no way to detect. So we recommend putting only metadata in parameters that are not strictly mission critical. This is useful to pass variables into the proof object instead of having to maintain state separately. For mission critical variables that should not be possible for the user to edit, please refer [`setContext`](preparing-request#set-context) instead. - -``` -reclaimProofRequest.setParams({ - action: "account_verification", - timestamp: Date.now(), - ... -}); -``` - - - - diff --git a/content/docs/js-sdk/preparing-request.mdx b/content/docs/js-sdk/preparing-request.mdx index f6f83f9..b54697e 100644 --- a/content/docs/js-sdk/preparing-request.mdx +++ b/content/docs/js-sdk/preparing-request.mdx @@ -17,7 +17,7 @@ This is the simplest version of creating a proof request. import { ReclaimProofRequest } from '@reclaimprotocol/js-sdk'; ``` -## Create an endpoint to build the `Proof Request` on your backend +## Setup a request on the backend ```javascript const reclaimProofRequest = await ReclaimProofRequest.init( 'APP_ID', @@ -84,6 +84,18 @@ reclaimProofRequest.setContext('address', 'message') - `address` : this is usually a unique identifier for the user. This could be an email address, a wallet address, or just a session id - `message` : this is an open field where you can add any other information that you want passed around from the build request to the callback endpoint. You can stringify jsons here for convenience. +## Set Parameters +If you already know what the value of the extracted parameter is supposed to be, you can set that using `setParams`. +For example, if you know that the user's name before hand - and you want them to prove something from a website and you need the name to match exactly, you should use set the name in the params. + +If the extracted parameter doesn't match the set parameter, the proof generation will fail. +``` +reclaimProofRequest.setParams({ + name : "John Doe" +}) +``` + + ## Set Callback ``` reclaimProofRequest.setAppCallbackUrl(url) diff --git a/content/docs/js-sdk/verifying-proofs.mdx b/content/docs/js-sdk/verifying-proofs.mdx index ef5c72e..b8d1ae5 100644 --- a/content/docs/js-sdk/verifying-proofs.mdx +++ b/content/docs/js-sdk/verifying-proofs.mdx @@ -4,7 +4,7 @@ description: Critical step to make sure user is not trying to defraud your app --- # Why do I need to verify, when the proof has already been generated? -The [proof generation](/js-sdk/generating-proof) is a client side operation to protect the privacy and security of the user. However, if the user is malicious and you don't verify the proof on the backend, the user could use browser injections to trick your webapp to call `onSuccess` callback even without creating a valid proof. So, you must force your frontend to upload the proof generated or claimed to have been generated and verify them before you take the user to the next step in your business logic. +The [proof generation](/js-sdk/generating-proof) is a client side operation. On Success Callback is only responsible for notifying when the proof is generated successfully. All the proofs generated should be verified on your backend as a malicious user can bypass any check you add on the frontend. Verifying proofs is a very simple light weight operation. You can think of it as verifying the digital signatures to make sure the data is tamper resistant. From 8a570a1cbc71c67b441c76f7f4b75e2669ed392b Mon Sep 17 00:00:00 2001 From: madhavanmalolan Date: Thu, 13 Nov 2025 00:45:02 +0000 Subject: [PATCH 3/5] fixing setParams doc --- content/docs/js-sdk/meta.json | 2 +- content/docs/js-sdk/preparing-request.mdx | 6 ------ 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/content/docs/js-sdk/meta.json b/content/docs/js-sdk/meta.json index 9229a33..36c6683 100644 --- a/content/docs/js-sdk/meta.json +++ b/content/docs/js-sdk/meta.json @@ -1,5 +1,5 @@ { - "title": "NextJS/React SDK", + "title": "Javascript SDK", "pages": [ "installation", "preparing-request", diff --git a/content/docs/js-sdk/preparing-request.mdx b/content/docs/js-sdk/preparing-request.mdx index b54697e..75a6c43 100644 --- a/content/docs/js-sdk/preparing-request.mdx +++ b/content/docs/js-sdk/preparing-request.mdx @@ -3,12 +3,6 @@ title: Preparing the proof request description: Create a request for a proof generation on the backend --- -# What is a proof request? -You need to prepare a proof request that will then be presented to the user on the frontend. -This proof request, most importantly, tells the user -1. With which application they will be sharing the data with -2. What is it that they need to prove to the said application - # Quickstart This is the simplest version of creating a proof request. From c063624a5d3fe3f4db070e9da0295fd8fd6f60a6 Mon Sep 17 00:00:00 2001 From: madhavanmalolan Date: Thu, 13 Nov 2025 14:03:19 +0000 Subject: [PATCH 4/5] json in callback --- content/docs/js-sdk/preparing-request.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/js-sdk/preparing-request.mdx b/content/docs/js-sdk/preparing-request.mdx index 75a6c43..7c539fe 100644 --- a/content/docs/js-sdk/preparing-request.mdx +++ b/content/docs/js-sdk/preparing-request.mdx @@ -92,6 +92,8 @@ reclaimProofRequest.setParams({ ## Set Callback ``` -reclaimProofRequest.setAppCallbackUrl(url) +reclaimProofRequest.setAppCallbackUrl(url, useJson) ``` Set a backend callback URL where Reclaim Protocol will POST proofs directly after verification. This enables secure backend proof processing without relying on frontend to upload the proof. + +If `useJson` is set to `true`, it will send the proof as a raw JSON. Else, the POST body will contain the Proof JSON urlencoded. From 26bb9c363ee6b997b8ffdd6d13f6ff0797776998 Mon Sep 17 00:00:00 2001 From: madhavanmalolan Date: Thu, 13 Nov 2025 14:39:16 +0000 Subject: [PATCH 5/5] reference implementation for websdk --- content/docs/js-sdk/preparing-request.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/js-sdk/preparing-request.mdx b/content/docs/js-sdk/preparing-request.mdx index 7c539fe..a648c23 100644 --- a/content/docs/js-sdk/preparing-request.mdx +++ b/content/docs/js-sdk/preparing-request.mdx @@ -66,9 +66,9 @@ proofRequestOptions = { useAppClip: false, customSharePageUrl: 'CONTACT_SUPPORT_FOR_URL' } - const proofRequest = await ReclaimProofRequest.init(appId, appSecret, providerId, proofRequestOptions); ``` +[See reference implementation](https://github.com/reclaimprotocol/websdk-demo) ## Set Context You can set context to the proof request that helps identify the request when you receive it back in the callback.