From d41423bc4c12374541261799fa9fe8ef2a75eee4 Mon Sep 17 00:00:00 2001 From: Kushal7788 Date: Tue, 3 Jun 2025 12:45:54 +0530 Subject: [PATCH] Browser Extension Docs for JS SDK --- .../docs/advance-options/advance-options.mdx | 130 ++++++++++----- content/docs/web/frontend/fullstack.mdx | 151 +++++++++--------- content/docs/web/frontend/quickstart.mdx | 105 +++++++++++- 3 files changed, 271 insertions(+), 115 deletions(-) diff --git a/content/docs/advance-options/advance-options.mdx b/content/docs/advance-options/advance-options.mdx index 3736ef9..63c20c9 100644 --- a/content/docs/advance-options/advance-options.mdx +++ b/content/docs/advance-options/advance-options.mdx @@ -7,7 +7,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; Before exploring advanced options, ensure you're familiar with the Basic Usage guide for your platform. - All advanced options should be set before calling `getRequestUrl()`. These options work for both frontend and backend implementations. + All advanced options should be set before calling `getRequestUrl()` or `triggerReclaimFlow()`. These options work for both frontend and backend implementations. ## Advanced Options @@ -16,47 +16,25 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; When initializing the SDK, you can pass additional options to customize its behavior: - + ```javascript const proofRequest = await ReclaimProofRequest.init( 'YOUR_RECLAIM_APP_ID', 'YOUR_RECLAIM_APP_SECRET', 'YOUR_PROVIDER_ID', - { useAppClip: true, device: "ios", log: true } + { + useAppClip: true, + log: true, + useBrowserExtension: true, + extensionID: 'custom-extension-id' + } ) ``` - `useAppClip`: When set to `true`, the SDK will give an App Clip url when calling `getRequestUrl()` which allows to open the reclaim verifier app directly from your application. - - `device`: When set to `ios` the appClip url will be generated for ios and when set to `android` the appClip url will be generated for android devices. By default it is set to `android`. - - `log`: When set to `true`, enables detailed logging for debugging purposes. - - - ```javascript - const proofRequest = await ReclaimProofRequest.init( - 'YOUR_RECLAIM_APP_ID', - 'YOUR_RECLAIM_APP_SECRET', - 'YOUR_PROVIDER_ID', - { useAppClip: true, log: true } - ) - ``` - - `useAppClip`: When set to `true`, the SDK will give an App Clip url(for ios) and instant app url(for android) when calling `getRequestUrl()` which allows to open the reclaim verifier app directly from your application. - - `log`: When set to `true`, enables detailed logging for debugging purposes. - - - - ```dart - import 'package:reclaim_sdk/utils/types.dart'; - import 'package:reclaim_sdk/reclaim.dart'; - - final proofRequest = await ReclaimProofRequest.init( - 'YOUR_RECLAIM_APP_ID', - 'YOUR_RECLAIM_APP_SECRET', - 'YOUR_PROVIDER_ID', - ProofRequestOptions(useAppClip: true, log: true) - ); - ``` - - `useAppClip`: When set to `true`, the SDK will give an App Clip url(for ios) and instant app url(for android) when calling `getRequestUrl()` which allows to open the reclaim verifier app directly from your application. - `log`: When set to `true`, enables detailed logging for debugging purposes. + - `useBrowserExtension`: When set to `true` (default), enables browser extension support for seamless desktop verification. + - `extensionID`: Custom extension identifier if using a different browser extension. ```python @@ -73,12 +51,73 @@ When initializing the SDK, you can pass additional options to customize its beha - Use this option to enhance debugging capabilities in your application. The logging option is particularly useful during development and testing phases. + +### Checking Extension Availability + + + + ```javascript + 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') + } + ``` + + + +### Modal Customization + +When the QR code modal is displayed (fallback on desktop), you can customize its appearance and behavior: + + + + ```javascript + 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' // Custom extension 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`: Boolean to enable dark theme styling +- `extensionUrl`: Custom URL for browser extension download/installation + + + Modal customization allows you to maintain brand consistency and provide clear instructions to your users about the verification process. + + ### Adding Context Use the `addContext` method to include additional information in your proof request. This context helps identify and differentiate between various proof requests in the resulting proof object. @@ -94,7 +133,10 @@ Use the `addContext` method to include additional information in your proof requ reclaimProofRequest.addContext('0x1234567890abcdef', 'User registration proof') + // Works with both traditional and streamlined flows const requestUrl = await reclaimProofRequest.getRequestUrl() + // OR + await reclaimProofRequest.triggerReclaimFlow() ``` @@ -165,6 +207,9 @@ The `setParams` method lets you define specific conditions for proof generation, industry: 'Technology' }) + // Works with both flows + await reclaimProofRequest.triggerReclaimFlow() + // OR const requestUrl = await reclaimProofRequest.getRequestUrl() ``` @@ -238,10 +283,13 @@ The `setRedirectUrl` method allows you to specify a custom URL where users will reclaimProofRequest.setRedirectUrl('https://your-app.com/verification-complete') + // Works with both traditional and streamlined flows + await reclaimProofRequest.triggerReclaimFlow() + // OR const requestUrl = await reclaimProofRequest.getRequestUrl() ``` - This enhances user experience by seamlessly guiding users back to your application after proof generation. Ensure the redirect URL is prepared to handle post-verification logic. + This enhances user experience by seamlessly guiding users back to your application after proof generation. Ensure the redirect URL is prepared to handle post-verification logic. Works seamlessly with the streamlined `triggerReclaimFlow()` method. @@ -338,6 +386,9 @@ The `setAppCallbackUrl` method allows you to specify a custom API endpoint where reclaimProofRequest.setAppCallbackUrl('https://your-api.com/receive-proofs') + // Works with both flows - proofs sent to callback regardless of method + await reclaimProofRequest.triggerReclaimFlow() + // OR const requestUrl = await reclaimProofRequest.getRequestUrl() ``` @@ -390,7 +441,7 @@ The `setAppCallbackUrl` method allows you to specify a custom API endpoint where - This method is particularly useful for backend implementations. It allows you to receive proofs directly without polling the status URL. Ensure your endpoint is secure and can handle incoming proof data. Make sure to proper middleware to parse the proof object in the response. Eg. `express.text({ type: '*/*', limit: '50mb' })` in express.js. + This method is particularly useful for backend implementations. It allows you to receive proofs directly without polling the status URL. Ensure your endpoint is secure and can handle incoming proof data. Make sure to proper middleware to parse the proof object in the response. Eg. `express.text({ type: '*/*', limit: '50mb' })` in express.js. Works with both traditional and streamlined verification flows. ### Exporting and Importing SDK Configuration @@ -411,6 +462,10 @@ The SDK provides methods to export and import the entire configuration as a JSON // On a different service or application import the configuration const reclaimProofRequest = await ReclaimProofRequest.fromJsonString(reclaimProofRequestConfig) + + // Use with either flow method + await reclaimProofRequest.triggerReclaimFlow() + // OR const requestUrl = await reclaimProofRequest.getRequestUrl() ``` @@ -465,7 +520,7 @@ The SDK provides methods to export and import the entire configuration as a JSON - This feature is particularly useful when you need to initialize the SDK in one part of your application (e.g., frontend) and use it in another (e.g., backend). It provides a seamless way to transfer the configuration. + This feature is particularly useful when you need to initialize the SDK in one part of your application (e.g., frontend) and use it in another (e.g., backend). It provides a seamless way to transfer the configuration. The exported configuration maintains all settings including modal customization and browser extension preferences. ### Verifying Proof Signatures @@ -563,10 +618,9 @@ The SDK provides a method to verify the cryptographic signatures of proofs to en - The `verifyProof` method checks the cryptographic signatures in the proof against the attestor's public key to ensure the proof hasn't been tampered with. Always verify proofs before accepting them as valid, especially when receiving them from different application sources. + The `verifyProof` method checks the cryptographic signatures in the proof against the attestor's public key to ensure the proof hasn't been tampered with. Always verify proofs before accepting them as valid, especially when receiving them from different application sources. This verification works regardless of whether the proof was generated using traditional or streamlined flows. - ## 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: diff --git a/content/docs/web/frontend/fullstack.mdx b/content/docs/web/frontend/fullstack.mdx index c8b761e..3709ce8 100644 --- a/content/docs/web/frontend/fullstack.mdx +++ b/content/docs/web/frontend/fullstack.mdx @@ -29,15 +29,87 @@ This guide will assume the backend has been deployed. ### 2. Frontend Implementation -Here's a step-by-step implementation showing how to initialize and use the Reclaim SDK in your frontend application: +### Streamlined Implementation with triggerReclaimFlow (Recommended) + +The modern approach uses the `triggerReclaimFlow()` method which automatically handles platform detection and provides the optimal user experience. Here's how to integrate it with your backend: -Setup the variables and imports. ```javascript +import { useState } from 'react'; import { ReclaimProofRequest } from '@reclaimprotocol/js-sdk'; -const BASE_URL = "https://your-domain.com"; //if using ngrok, use the ngrok base url here + +const BASE_URL = "https://your-domain.com"; // if using ngrok, use the ngrok base url here + +function ReclaimDemo() { + const [proofs, setProofs] = useState(null); + const [isLoading, setIsLoading] = useState(false); + + const handleVerification = async () => { + try { + setIsLoading(true); + + // Step 1: Fetch the configuration from your backend + const response = await fetch(BASE_URL + '/generate-config'); + const { reclaimProofRequestConfig } = await response.json(); + + // Step 2: Initialize the ReclaimProofRequest with the received configuration + const reclaimProofRequest = await ReclaimProofRequest.fromJsonString(reclaimProofRequestConfig); + + // Step 3: Trigger the verification flow automatically + // This method detects the user's platform and provides the optimal experience: + // - Browser extension for desktop users (if installed) + // - QR code modal for desktop users (fallback) + // - Native app clips for mobile users + await reclaimProofRequest.triggerReclaimFlow(); + + // Step 4: Start listening for proof submissions + await reclaimProofRequest.startSession({ + onSuccess: (proofs) => { + console.log('Successfully created proof', proofs); + setProofs(proofs); + setIsLoading(false); + // Handle successful verification - proofs are also sent to your backend callback + }, + onError: (error) => { + console.error('Verification failed', error); + setIsLoading(false); + // Handle verification failure + }, + }); + + } catch (error) { + console.error('Error initializing Reclaim:', error); + setIsLoading(false); + // Handle initialization error (e.g., show error message) + } + }; + + return ( + <> + + + {proofs && ( +
+

Verification Successful!

+ 
{JSON.stringify(proofs, null, 2)}
+
+ )} + + ); +} + +export default ReclaimDemo; ``` -Create the function to create verification request, that calls the backend +### Customizing the Modal (Optional) + +You can customize the modal appearance and behavior using the `setModalOptions()` method. Check out the [advanced configuration options](./quickstart#advanced-configuration-options) for more details. + +### Traditional Implementation Guide + +For more control over the verification flow, you can use the traditional approach: + ```javascript const getVerificationReq = async () => { @@ -105,74 +177,3 @@ Once `requestUrl` is set, display the QR or button for user to initiate verifica ``` -### All put together -```javascript -import { useState } from 'react'; -import QRCode from 'react-qr-code'; -import { ReclaimProofRequest } from '@reclaimprotocol/js-sdk'; - -const BASE_URL = "https://your-domain.com"; //if using ngrok, use the ngrok base url here - - -function ReclaimDemo() { - // State to store the verification request URL - // request URL is what triggers the AppClip/InstantApp - const [requestUrl, setRequestUrl] = useState(''); - const [proofs, setProofs] = useState([]); - -const getVerificationReq = async () => { - - try { - // Step 1: Fetch the configuration from your backend - const response = await fetch(BASE_URL+'/generate-config'); - const { reclaimProofRequestConfig } = await response.json(); - - // Step 2: Initialize the ReclaimProofRequest with the received configuration - const reclaimProofRequest = await ReclaimProofRequest.fromJsonString(reclaimProofRequestConfig); - - // Step 3: Generate the request URL for the verification process - const requestUrl = await reclaimProofRequest.getRequestUrl(); - setRequestUrl(requestUrl); - - // Step 4: Start the verification session - await reclaimProofRequest.startSession({ - onSuccess: (proofs) => { - console.log("successfully created proof", proof); - // Handle successful verification - }, - onError: (error) => { - console.error('Verification failed', error); - // Handle verification failure - }, - }); - - console.log('Request URL:', requestUrl); - } catch (error) { - console.error('Error initializing Reclaim:', error); - // Handle initialization error (e.g., show error message) - } -} - - return ( - <> - - {/* Display QR code when URL is available */} - {requestUrl && ( -
- -
- Open Link -
- )} - {proofs && ( -
-

Verification Successful!

- 
{JSON.stringify(proofs, null, 2)}
-
- )} - - ); -} - -export default ReclaimDemo; -``` diff --git a/content/docs/web/frontend/quickstart.mdx b/content/docs/web/frontend/quickstart.mdx index 987df5c..c4402e6 100644 --- a/content/docs/web/frontend/quickstart.mdx +++ b/content/docs/web/frontend/quickstart.mdx @@ -7,7 +7,107 @@ description: This is the fastest way to get an prototype running and experience - Install the React libraries using the [Installation guide](./installation) - Get the `APPLICATION_ID`, `APPLICATION_SECRET` and `PROVIDER_ID` using the [API Key guide](/api-key) -## Implementation Guide +## Streamlined Implementation with triggerReclaimFlow (Recommended) + +The Reclaim SDK now provides a simplified `triggerReclaimFlow()` method that automatically handles the verification process across different platforms and devices. This method intelligently chooses the best verification method based on the user's environment. + +```javascript +import { useState } from 'react'; +import { ReclaimProofRequest } from '@reclaimprotocol/js-sdk'; + +function ReclaimDemo() { + const [proofs, setProofs] = useState(null); + const [isLoading, setIsLoading] = useState(false); + + const handleVerification = async () => { + try { + setIsLoading(true); + + // Your credentials from the Reclaim Protocol Developer Portal + const APP_ID = 'YOUR_APPLICATION_ID'; + const APP_SECRET = 'YOUR_APPLICATION_SECRET'; + const PROVIDER_ID = 'YOUR_PROVIDER_ID'; + + // Initialize the Reclaim SDK with your credentials + const reclaimProofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID); + + // Trigger the verification flow automatically + // This method detects the user's platform and provides the optimal experience: + // - Browser extension for desktop users (if installed) + // - QR code modal for desktop users (fallback) + // - Native app clips for mobile users + await reclaimProofRequest.triggerReclaimFlow(); + + // Start listening for proof submissions + await reclaimProofRequest.startSession({ + onSuccess: (proofs) => { + console.log('Verification successful:', proofs); + setProofs(proofs); + setIsLoading(false); + }, + onError: (error) => { + console.error('Verification failed', error); + setIsLoading(false); + }, + }); + } catch (error) { + console.error('Error starting verification:', error); + setIsLoading(false); + } + }; + + return ( + <> + + + {proofs && ( +
+

Verification Successful!

+ 
{JSON.stringify(proofs, null, 2)}
+
+ )} + + ); +} + +export default ReclaimDemo; +``` + +### How triggerReclaimFlow() Works + +The `triggerReclaimFlow()` method automatically detects the user's environment and chooses the optimal verification method: + +#### On Desktop Browsers: +1. **Browser Extension First**: If the Reclaim browser extension is installed, it uses the extension for seamless in-browser verification. +2. **QR Code Modal Fallback**: If the extension is not available, it automatically displays a QR code modal for mobile scanning. + +#### On Mobile Devices: +1. **iOS Devices**: Automatically redirects to the Reclaim App Clip for native iOS verification. +2. **Android Devices**: Automatically redirects to the Reclaim Instant App for native Android verification. + +### Browser Extension Support + +You can also manually check for browser extension availability and customize the QR code modal: + +```javascript +// Check if browser extension is available +const isExtensionAvailable = await reclaimProofRequest.isBrowserExtensionAvailable(); +console.log('Extension available:', isExtensionAvailable); + +// Customize modal appearance (optional) +reclaimProofRequest.setModalOptions({ + title: 'Verify Your Account', + description: 'Scan the QR code with your mobile device or install our browser extension', + darkTheme: false, + extensionUrl: 'https://chrome.google.com/webstore/detail/reclaim' +}); +``` + +## Traditional Implementation Guide + +For more control over the verification flow, you can use the traditional approach: ```javascript import { useState } from 'react'; @@ -41,6 +141,7 @@ function ReclaimDemo() { // - Updating UI to show verification success // - Storing verification status // - Redirecting to another page + setProofs(proofs); }, // Called if there's an error during verification onError: (error) => { @@ -79,4 +180,4 @@ export default ReclaimDemo; ``` ## Get production Ready -For production usecases, you might want to make sure that the proofs are sent directly to your backend - so that the use doesn't have an opportunity to tamper with the data. For that implement the [Backend](../backend) and follow the [Fullstack guide](./fullstack) \ No newline at end of file +For production usecases, you might want to make sure that the proofs are sent directly to your backend - so that the user doesn't have an opportunity to tamper with the data. For that implement the [Backend](../backend) and follow the [Fullstack guide](./fullstack) \ No newline at end of file