Skip to content

Improve cancel callback documentation #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
predatorx7 merged 3 commits into from
Jan 31, 2026
Merged

Improve cancel callback documentation #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d9f944b
Improve cancel callback documentation
predatorx7 Jan 31, 2026
6b2d31f
Update docs for ReclaimVerificationAbortedException
predatorx7 Jan 31, 2026
efc9e39
Update request anatomy
predatorx7 Jan 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions content/docs/js-sdk/preparing-request.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +107 to +116
Copy link

@coderabbitai coderabbitai bot Jan 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Minor grammar and formatting fixes needed.

Two small issues:

  1. Line 109: Missing article "the" before "user"
  2. Line 116: "auto submit" should be hyphenated as "auto-submit" (compound adjective)
📝 Proposed fixes 
 #### 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.
+Following are some exceptions that happen when the user presses a button to cancel in the UI or a provider custom injection script causes a cancellation by calling `Reclaim.reportProviderError` in the 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) 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.
+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.
🧰 Tools
🪛 LanguageTool

[grammar] ~116-~116: Use a hyphen to join words.
Context: ...may also trigger this callback if auto submit is enabled. In any case, you ca...

(QB_NEW_EN_HYPHEN)

🤖 Prompt for AI Agents 
In `@content/docs/js-sdk/preparing-request.mdx` around lines 107 - 116, Fix two
minor wording issues in the "What triggers cancel callback?" section: add the
article "the" before "user" in the sentence "Following are some exceptions that
happen when user presses a button..." and hyphenate "auto submit" to
"auto-submit" in the sentence "Other errors (such as network timeouts or
internal exceptions) may also trigger this callback if auto submit is enabled."
Reference the section header and the exception names
ReclaimVerificationAbortedException and
ReclaimVerificationProviderScriptException to locate the paragraph to update.


## Redirect after proof generation or cancellation

Expand Down
1 change: 1 addition & 0 deletions content/docs/troubleshooting/analytics-event.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines 208 to +210
Copy link

@coderabbitai coderabbitai bot Jan 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Document has_error in the metadata type definition.

The new note introduces a has_error field, but MetadataReclaimException doesn’t include it. This makes the type definition inconsistent with the narrative.

📝 Suggested doc update 
 export interface MetadataReclaimException {
   exception: {
     type: string; // e.g. "ReclaimVerificationCancelledException"
     message: string;
     providerError?: Record<string, any>;
   };
+  has_error?: boolean;
 }
🤖 Prompt for AI Agents 
In `@content/docs/troubleshooting/analytics-event.mdx` around lines 208 - 210, The
docs mention a has_error boolean in Reclaim verification metadata but the
MetadataReclaimException type definition is missing it; update the
MetadataReclaimException metadata type to include an optional has_error?:
boolean (and add a short inline comment or sentence describing that it is true
when the user cancelled after an error) so the narrative and type definition
match—look for the MetadataReclaimException type definition in the
analytics-event content and add the optional has_error field to that type.

85 changes: 69 additions & 16 deletions content/docs/troubleshooting/anatomy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Comment on lines +36 to +58
Copy link

@coderabbitai coderabbitai bot Jan 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Align cancel callback description with the example configuration.

The comment says cancelCallbackUrl is only used when auto submit is enabled, but the example sets "canAutoSubmit": false, which can be read as contradictory. Consider clarifying the comment or adjusting the example value to avoid confusion.

✏️ Possible clarification 
-    // URL which is called when verification is cancelled by the user or after errors (only auto submit enabled; auto submit is enabled by default).
+    // URL called when the user cancels verification; error-triggered cancellations are delivered only when canAutoSubmit is true (default).
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
// 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,
// URL called when the user cancels verification; error-triggered cancellations are delivered only when canAutoSubmit is true (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,
🤖 Prompt for AI Agents 
In `@content/docs/troubleshooting/anatomy.mdx` around lines 36 - 58, The comment
for "cancelCallbackUrl" conflicts with the example because it says the URL is
used only when auto submit is enabled while the example sets "canAutoSubmit":
false; update the example or the comment: either set "canAutoSubmit": true in
the JSON sample to match the comment, or reword the comment to state that
"cancelCallbackUrl" is used when auto submit is enabled (canAutoSubmit: true)
and may be ignored when false; adjust the surrounding text for
"cancelCallbackUrl" and "canAutoSubmit" so their behaviors are consistent and
unambiguous.

// 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"
}
```

Expand Down Expand Up @@ -49,14 +100,15 @@ 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"
}
}
]
```

# Errors
# Structure of data POSTed to cancel callback

```json
{
Expand Down Expand Up @@ -91,5 +143,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)
9 changes: 4 additions & 5 deletions content/docs/troubleshooting/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down