Skip to content

docs: add provider versioning and update expo sdk docs #70

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
merged 1 commit into from
Jul 23, 2025
Merged

docs: add provider versioning and update expo sdk docs #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
48 changes: 48 additions & 0 deletions content/docs/advance-options/web-sdk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,54 @@ The `init` method allows you to pass additional options to customize the SDK's b
</Tab>
</Tabs>

### Provider Versioning (optional)

The Reclaim SDK supports semantic versioning for all providers, allowing you to optionally lock to specific versions and avoid unexpected schema changes during integration. Specifying a provider version is optional—if you do not provide one, the SDK will use the latest available version by default.

#### Key Features

- **Semantic Versioning**: All providers follow `MAJOR.MINOR.PATCH` format (e.g., `1.0.0`).
- **Automated Versioning**: Provider changes automatically bump the version based on impact.

#### Version Matching in SDK

The SDK supports flexible version targeting:

- **Exact version**: `'1.0.0'`
- **Range operators**: `'>=1.0.0'`, `<2.0.0'`, etc.
- **Tilde (~) range**: `'~1.2.0'` resolves to the latest patch version in the `1.2.x` range.

#### Example


<Tabs items={['JavaScript', 'Python']}>
<Tab>
```javascript
const proofRequest = await ReclaimProofRequest.init(
'YOUR_RECLAIM_APP_ID',
'YOUR_RECLAIM_APP_SECRET',
'YOUR_PROVIDER_ID',
{
providerVersion: '1.0.0' // locks to specific schema version
}
)
```
</Tab>
<Tab>
```python
from reclaim_python_sdk.proof_request import ReclaimProofRequest

proof_request = await ReclaimProofRequest.init(
'YOUR_RECLAIM_APP_ID',
'YOUR_RECLAIM_APP_SECRET',
'YOUR_PROVIDER_ID',
# optional fields
options={'provider_version': '1.0.0'} # locks to specific schema version
)
```
</Tab>
</Tabs>

### setAppCallbackUrl()

The `setAppCallbackUrl` method allows you to specify a custom API endpoint where verification credentials(proofs) will be sent upon successful generation.
Expand Down
14 changes: 9 additions & 5 deletions content/docs/expo/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Installation
description: Welcome to the first step in integrating Reclaim Protocol into your React Native Expo project! This guide will walk you through the installation process and help you get started quickly.
description: Welcome to the first step in integrating Reclaim Protocol's InApp SDK into your React Native Expo project! This guide will walk you through the installation process and help you get started quickly.
---

## Prerequisites
Expand All @@ -23,17 +23,17 @@ Navigate to your React Native Expo project's root directory and execute one of t

Using npm:
```bash
npm install @reclaimprotocol/reactnative-sdk
npm install @reclaimprotocol/inapp-rn-sdk
```

Using yarn:
```bash
yarn add @reclaimprotocol/reactnative-sdk
yarn add @reclaimprotocol/inapp-rn-sdk
```

Using Expo CLI:
```bash
npx expo install @reclaimprotocol/reactnative-sdk
npx expo install @reclaimprotocol/inapp-rn-sdk
```

### 2. Expo Configuration
Expand Down Expand Up @@ -107,7 +107,7 @@ Replace `your-app-scheme`, `your-domain.com`, and package identifiers with your

Now that you've installed the SDK successfully, you can:

1. Follow the [Usage](./usage) guide to create your first proof request
1. Follow the [Usage](./usage) guide to create your first verification request
2. Explore [Advance Options](../advance-options/web-sdk) for customization

### Troubleshooting
Expand All @@ -129,3 +129,7 @@ eas build --profile development --platform all --clear-cache
<Callout type="tip">
Keep your SDK and Expo SDK versions up to date by regularly checking for updates using `npx expo install --fix`.
</Callout>

<Callout type="warning">
**Compatibility Notice**: Please be aware of a known incompatibility between ReclaimInAppSdk and the `expo-dev-client` package on the iOS platform. When both packages are present in your iOS application, critical network requests from ReclaimInAppSdk may fail with a request timeout error. We recommend temporarily removing expo-dev-client from your project when you need to test or use ReclaimInAppSdk functionality on iOS.
</Callout>
179 changes: 98 additions & 81 deletions content/docs/expo/usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
title: Usage
description: Learn how to integrate and use Reclaim Protocol in your React Native Expo app, from initialization to handling proof requests and responses.
description: Learn how to integrate and use Reclaim Protocol's InApp SDK in your React Native Expo app, from initialization to handling verification requests and responses.
---

## Prerequisites

Before implementing the Reclaim Protocol SDK in your React Native Expo application, ensure you have:
Before implementing the Reclaim Protocol InApp SDK in your React Native Expo application, ensure you have:

- Installed the Reclaim Protocol SDK (detailed instructions in the [Installation Guide](./installation))
- Installed the Reclaim Protocol InApp SDK (detailed instructions in the [Installation Guide](./installation))
- Obtained your credentials from the [Reclaim Developer Portal](https://dev.reclaimprotocol.org/):
- Application ID
- Application Secret
Expand All @@ -19,129 +19,146 @@ Before implementing the Reclaim Protocol SDK in your React Native Expo applicati

### 1. Import Required Dependencies

Start by importing the necessary React Native, Expo, and Reclaim Protocol components:
Start by importing the necessary React Native, Expo, and Reclaim Protocol InApp SDK components:

```javascript
import React, { useState, useEffect } from 'react';
import { View, Text, Button, Linking } from 'react-native';
import { ReclaimProofRequest } from '@reclaimprotocol/reactnative-sdk';
import React, { useState } from 'react';
import { View, Text, Button, Alert } from 'react-native';
import { ReclaimVerification } from '@reclaimprotocol/inapp-rn-sdk';
```

### 2. SDK Initialization

Configure the SDK with your credentials:
Initialize the ReclaimVerification class to create an instance:

```javascript
const APP_ID = 'YOUR_APPLICATION_ID';
const APP_SECRET = 'YOUR_APPLICATION_SECRET';
const PROVIDER_ID = 'YOUR_PROVIDER_ID';

async function initializeReclaim() {
const reclaimProofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID);
return reclaimProofRequest;
}
const reclaimVerification = new ReclaimVerification();
```
Comment on lines +32 to 40
Copy link

@coderabbitai coderabbitai bot Jul 23, 2025

Choose a reason for hiding this comment

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

⚠️ Potential issue

Security notice contradicts example – secret placed in client code

Line 16 warns “Never include your Application Secret in client-side code”, yet the snippet hard-codes APP_SECRET.
Either move the secret to a secure backend example or add a disclaimer explaining this is only for demo purposes.

🤖 Prompt for AI Agents 
In content/docs/expo/usage.mdx around lines 32 to 40, the example code
hard-codes the APP_SECRET in client-side code, which contradicts the security
notice on line 16 advising against this. To fix, either move the APP_SECRET
usage to a backend example or add a clear disclaimer in the snippet stating that
hard-coding the secret is only for demonstration purposes and should never be
done in production client code.


<Callout type="info">
Replace the placeholder credentials with your actual values from the Reclaim Developer Portal.
</Callout>

### 3. Request URL Generation
### 3. Start Verification Flow

Create a verification request URL for users:
Start the verification flow by providing the app id, secret and provider id:

```javascript
async function generateRequestUrl(reclaimProofRequest) {
const requestUrl = await reclaimProofRequest.getRequestUrl();
console.log('Request URL:', requestUrl);
return requestUrl;
async function startVerification() {
try {
const verificationResult = await reclaimVerification.startVerification({
appId: APP_ID,
secret: APP_SECRET,
providerId: PROVIDER_ID,
});

// Handle successful verification
if (verificationResult.proofs) {
console.log('Verification successful:', verificationResult.proofs);
return verificationResult;
}
} catch (error) {
// Handle verification errors
handleVerificationError(error);
}
}
```

### 4. Verification Session Management
### 4. Exception Handling

Set up the verification session listener:
Handle verification exceptions using the ReclaimVerificationException:

```javascript
async function startVerificationSession(reclaimProofRequest, onSuccess, onError) {
await reclaimProofRequest.startSession({
onSuccess: onSuccess,
onError: onError,
});
function handleVerificationError(error) {
if (error instanceof ReclaimVerification.ReclaimVerificationException) {
switch (error.type) {
case ReclaimVerification.ExceptionType.Cancelled:
Alert.alert('Verification Cancelled', 'The verification process was cancelled by the user.');
break;
case ReclaimVerification.ExceptionType.Dismissed:
Alert.alert('Verification Dismissed', 'The verification process was dismissed.');
break;
case ReclaimVerification.ExceptionType.SessionExpired:
Alert.alert('Session Expired', 'The verification session has expired. Please try again.');
break;
case ReclaimVerification.ExceptionType.Failed:
default:
Alert.alert('Verification Failed', 'The verification process failed. Please try again.');
}

// Access additional error details
console.log('Session ID:', error.sessionId);
console.log('Reason:', error.reason);
console.log('Inner Error:', error.innerError);
} else {
Alert.alert('Error', error instanceof Error ? error.message : 'An unknown verification error occurred');
}
}
```

### 5. React Native Expo Component Implementation

The following component demonstrates a complete integration of the Reclaim Protocol:
The following component demonstrates a complete integration of the Reclaim Protocol InApp SDK:

```javascript
function ReclaimDemo() {
// State management for URL and verification status
const [requestUrl, setRequestUrl] = useState('');
const [status, setStatus] = useState('');

useEffect(() => {
async function setup() {
try {
// Initialize SDK and generate request URL
const reclaimProofRequest = await initializeReclaim();
const url = await generateRequestUrl(reclaimProofRequest);
setRequestUrl(url);
setStatus('Ready to start verification');

// Start listening for verification results
await startVerificationSession(
reclaimProofRequest,
(proofs) => {
if (proofs) {
if (typeof proofs === 'string') {
// Handle custom callback URL response
console.log('SDK Message:', proofs);
} else if (typeof proofs !== 'string') {
// Handle default callback URL response
if (Array.isArray(proofs)) {
// when using provider with multiple proofs, we get an array of proofs
console.log('Proof received:', JSON.stringify(proofs.map(p => p.claimData.context)));
} else {
// when using provider with a single proof, we get a single proof object
console.log('Proof received:', JSON.stringify(proofs.claimData.context));
}
}
setStatus('Proof received!');
}
},
(error) => {
console.error('Verification failed', error);
setStatus(`Error: ${error.message}`);
}
);
} catch (error) {
console.error('Setup failed', error);
setStatus(`Setup failed: ${error.message}`);
const [status, setStatus] = useState('Ready to start verification');
const [isVerifying, setIsVerifying] = useState(false);

const handleStartVerification = async () => {
setIsVerifying(true);
setStatus('Starting verification...');

try {
const result = await startVerification();
if (result && result.proofs) {
setStatus('Verification successful!');
console.log('Proofs received:', result.proofs);
}
}

setup();
}, []);

const openRequestUrl = () => {
if (requestUrl) {
Linking.openURL(requestUrl);
} catch (error) {
setStatus('Verification failed');
handleVerificationError(error);
} finally {
setIsVerifying(false);
}
};

return (
<View style={{ padding: 20 }}>
<Text style={{ fontSize: 24, fontWeight: 'bold' }}>Reclaim Demo</Text>
<Text>Status: {status}</Text>
{requestUrl && <Button title="Start Verification" onPress={openRequestUrl} />}
<Text style={{ fontSize: 24, fontWeight: 'bold' }}>Reclaim InApp Demo</Text>
<Text style={{ marginVertical: 10 }}>Status: {status}</Text>
<Button
title={isVerifying ? "Verifying..." : "Start Verification"}
onPress={handleStartVerification}
disabled={isVerifying}
/>
</View>
);
}
```


## Advance Usage
## Advanced Usage

### Overriding SDK Config

You can customize the SDK behavior by overriding default configurations:

```javascript
// Override SDK configuration
reclaimVerification.setOverrides({
appInfo: {
appName: "Your Custom App Name",
appImageUrl: "https://your-domain.com/app-icon.png"
}
// Add other overrides as needed
});
```

### Available Functions

You can check out available functions in the SDK in the [Advance Options](../advance-options/web-sdk) guide
You can check out available functions and advanced options in the [Advance Options](../advance-options/web-sdk) guide.