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..50909c6 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,7 +136,31 @@ 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) +``` 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..36c6683 100644 --- a/content/docs/js-sdk/meta.json +++ b/content/docs/js-sdk/meta.json @@ -1,10 +1,9 @@ { - "title": "JavaScript SDK", + "title": "Javascript 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..a648c23 100644 --- a/content/docs/js-sdk/preparing-request.mdx +++ b/content/docs/js-sdk/preparing-request.mdx @@ -3,21 +3,15 @@ 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 proof -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` +## Setup a request on the backend ```javascript const reclaimProofRequest = await ReclaimProofRequest.init( 'APP_ID', @@ -28,13 +22,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 +44,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 +55,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); +``` +[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. ``` @@ -80,3 +78,22 @@ 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, 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. diff --git a/content/docs/js-sdk/verifying-proofs.mdx b/content/docs/js-sdk/verifying-proofs.mdx index 0c0c245..b8d1ae5 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. 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 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 {