From d9f944b53835707b60cd994508b76c99735c1aa3 Mon Sep 17 00:00:00 2001 From: Mushaheed Syed Date: Sat, 31 Jan 2026 16:15:51 +0530 Subject: [PATCH 1/3] Improve cancel callback documentation --- content/docs/js-sdk/preparing-request.mdx | 6 ++++-- content/docs/troubleshooting/index.mdx | 9 ++++----- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/content/docs/js-sdk/preparing-request.mdx b/content/docs/js-sdk/preparing-request.mdx index 93b3b39..6eb8d98 100644 --- a/content/docs/js-sdk/preparing-request.mdx +++ b/content/docs/js-sdk/preparing-request.mdx @@ -104,14 +104,16 @@ If the user cancels the session midway or after error, Reclaim will send a POST } ``` -Currently, **only these two types** will trigger the cancel callback: +#### What triggers cancel callback? + +Following are some exceptions that happen when user presses a button to cancel in UI or provider custom injection script causes a cancellation by calling `Reclaim.reportProviderError` in browser. | Exception Name | Description | |----------------|-------------| | `ReclaimVerificationAbortedException` | User cancelled the verification (e.g., tapped on cancel or verify another way button). | | `ReclaimVerificationProviderScriptException` | The provider script encountered an error (e.g., login failed, invalid account used). | -Other errors (such as network timeouts or internal exceptions) will **not** trigger this callback but can be found by [fetching analytics events](./troubleshooting/analytics-event) for the session. +Other errors (such as network timeouts or internal exceptions) may also trigger this callback if **auto submit is enabled**. In any case, you can always find the complete list of errors by [fetching analytics events](./troubleshooting/analytics-event) for the session. ## Redirect after proof generation or cancellation diff --git a/content/docs/troubleshooting/index.mdx b/content/docs/troubleshooting/index.mdx index 5bf307e..a26ab44 100644 --- a/content/docs/troubleshooting/index.mdx +++ b/content/docs/troubleshooting/index.mdx @@ -5,11 +5,10 @@ description: Learn how to handle errors, monitor verification status, and debug When integrating Reclaim Protocol, you have multiple tools at your disposal to monitor the status of detailed verifications and troubleshoot issues. This guide covers: -1. **[Handling Cancellation & Errors](#handling-cancellation--errors):** Receive immediate feedback in your application when a verification is cancelled. -2. **[Handle 'Verify Another Way'](#handle-verify-another-way):** Receive immediate feedback when the user chooses to verify in another way. -3. **[Server-Side Analytics](#server-side-analytics-events):** Fetch detailed session logs from the Reclaim server for analysis. -4. **[Client-Side Logs](#client-side-debugging):** Listen to real-time logs emitted by the SDKs on the user's device. -5. **[Troubleshooting Mode](#troubleshooting-mode):** Manually enable verbose logging in the verify UI for support tickets. +1. **[Handling Cancellation & Errors](#handling-cancellation--errors):** Receive immediate feedback in your application when a verification is cancelled (by actions such as the user choosing to verify in another way). +2. **[Server-Side Analytics](#server-side-analytics-events):** Fetch detailed session logs from the Reclaim server for analysis. +3. **[Client-Side Logs](#client-side-debugging):** Listen to real-time logs emitted by the SDKs on the user's device. +4. **[Troubleshooting Mode](#troubleshooting-mode):** Manually enable verbose logging in the verify UI for support tickets. --- From 6b2d31f7c529793e5117c30f79b9e9045dce7aa5 Mon Sep 17 00:00:00 2001 From: Mushaheed Syed Date: Sat, 31 Jan 2026 20:42:22 +0530 Subject: [PATCH 2/3] Update docs for ReclaimVerificationAbortedException --- content/docs/troubleshooting/analytics-event.mdx | 1 + content/docs/troubleshooting/anatomy.mdx | 1 + 2 files changed, 2 insertions(+) diff --git a/content/docs/troubleshooting/analytics-event.mdx b/content/docs/troubleshooting/analytics-event.mdx index 9dc2bb2..7148b61 100644 --- a/content/docs/troubleshooting/analytics-event.mdx +++ b/content/docs/troubleshooting/analytics-event.mdx @@ -207,3 +207,4 @@ When the `logType` is `RECLAIM_EXCEPTION`, the `metadata` string parses to an ob > [!NOTE] > In case of `ReclaimVerificationProviderScriptException`, the metadata may contain an additional `providerError` field with more detailed error information from the provider script. +> In case of `ReclaimVerificationAbortedException`, the metadata may contain an additional `has_error` boolean field which will be true if the user cancelled the verification after an error occurred during verification. diff --git a/content/docs/troubleshooting/anatomy.mdx b/content/docs/troubleshooting/anatomy.mdx index 59cf04f..275c8d1 100644 --- a/content/docs/troubleshooting/anatomy.mdx +++ b/content/docs/troubleshooting/anatomy.mdx @@ -91,5 +91,6 @@ When the `logType` is `RECLAIM_EXCEPTION`, the `metadata` string parses to an ob > [!NOTE] > In case of `ReclaimVerificationProviderScriptException`, the metadata may contain an additional `providerError` field with more detailed error information from the provider script. +> In case of `ReclaimVerificationAbortedException`, the metadata may contain an additional `has_error` boolean field which will be true if the user cancelled the verification after an error occurred during verification. You can see some common [reasons of failures here](./potential-failure-reasons) From efc9e3903eb7e9f457576d5a4338bfd05b57f7bc Mon Sep 17 00:00:00 2001 From: Mushaheed Syed Date: Sat, 31 Jan 2026 20:57:49 +0530 Subject: [PATCH 3/3] Update request anatomy --- content/docs/troubleshooting/anatomy.mdx | 84 +++++++++++++++++++----- 1 file changed, 68 insertions(+), 16 deletions(-) diff --git a/content/docs/troubleshooting/anatomy.mdx b/content/docs/troubleshooting/anatomy.mdx index 275c8d1..a8f290e 100644 --- a/content/docs/troubleshooting/anatomy.mdx +++ b/content/docs/troubleshooting/anatomy.mdx @@ -4,23 +4,74 @@ description: Datastructures of messages transmitted during the verification proc --- # Proof Request + ```js { - "applicationId":"0x... YOUR APPLICATION ID", - "providerId":"bb96d0b0-... YOUR PROVIDER ID", - "sessionId":"e1fca89978", // sessionId created by Reclaim Protocol - "context":{"contextAddress":"Address you set","contextMessage":"message you set"}, - "appCallbackUrl":"https://yourwebsite.com/reclaim-callback ... you set", - "claimCreationType":"createClaim", - "parameters":{ ... any parameters you set }, - "signature":"signature using your app secret to know it came from your application", - "redirectUrl":"https://yourwebsite.com/redirecturl set by you", - "timestamp":"1769799659479", - "timeStamp":"1769799659479", - "options":{"useAppClip":false,"customSharePageUrl":"https://portal.reclaimprotocol.org/kernel","useBrowserExtension":true}, - "sdkVersion":"js-4.7.1", - "jsonProofResponse":true, - "resolvedProviderVersion":"1.3.0" + // This can be your application id + "applicationId": "0xsampleapplicationid", + // The ID of Provider you are using for verifications + "providerId": "example", + // A unique short sessionId created by Reclaim Protocol to identify this session + "sessionId": "123", + // Any JSON serializable data you want to be part of the proof generation process + "context": { + "user": "john@example.com", + "contextAddress":"Address you set", + "contextMessage":"message you set" + }, + // URL where proof(s) are submitted after all proofs are successfully generated + "appCallbackUrl": "https://api.example.com/success?session=def", + // The type of claim creation + "claimCreationType": "createClaim", + // The parameters used by the provider script and the requests involved in proof generation process + // This is a map of strings to strings. + "parameters": { + "user": "john@example.com" + }, + // Signature of the proof request using your application secret + // This signature is generated using your application secret to know it came from your application + "signature": "0xbbf1aad7bd65c6d0c37a5b6012c4dff217e190372d5e364bf8f2bf4ea9df3a080ec8b325b84b29e130d9b15401087b36bc4852367c8f93427c39ffb7b44b498d1c", + // URL to redirect to after successful proof generation + "redirectUrl": "https://example.com/success?session=def", + // URL which is called when verification is cancelled by the user or after errors (only auto submit enabled; auto submit is enabled by default). + "cancelCallbackUrl": "https://api.example.com/cancel?session=def", + // URL to redirect to after cancelled proof generation + "cancelRedirectUrl": "https://example.com/cancelled?session=def", + // Timestamp of the proof request + "timestamp": "1769867597546", + // legacy: same as above + "timeStamp": "1769867597546", + "options": { + // enables diagnostic logging for debugging purposes + "log": true, + // enables use of AI in verification journey + "acceptAiProviders": false, + // users may use Reclaim Verifier app clip or instant app for verification + "useAppClip": false, + // URL of the custom share page (optional) + "customSharePageUrl": "https://portal.reclaimprotocol.org", + "launchOptions": { + // enables deferred deep links flow + "canUseDeferredDeepLinksFlow": true + }, + // Enables auto submitting proofs on success or errors + "canAutoSubmit": false, + // Preferred locale for the UI in verification journey + "preferredLocale": "zh-Hant-HK", + // Metadata that can be used by the UI in verification journey + "metadata": { + // This is an example of metadata, actual values may depend on custom themes + "theme": "dark" + }, + // Enables use of browser extension for verification + "useBrowserExtension": true + }, + // The version of SDK that generated this JSON string request + "sdkVersion": "js-4.10.0", + // Whether to submit proof as JSON or URL encoded using HTTP POST to the success callback. Cancellation callback not affected. + "jsonProofResponse": false, + // The version of provider that should be used for verifications + "resolvedProviderVersion": "1.0.0" } ``` @@ -49,6 +100,7 @@ description: Datastructures of messages transmitted during the verification proc "url": "reclaimprotocol" } ], + // Optional: Extra data attached to any proof. This can be null, JSON string, array or map. In most cases, this is a JSON map or null. "publicData": { "KEY":"VALUE" } @@ -56,7 +108,7 @@ description: Datastructures of messages transmitted during the verification proc ] ``` -# Errors +# Structure of data POSTed to cancel callback ```json {