diff --git a/content/docs/react-native/installation.mdx b/content/docs/react-native/installation.mdx index 6a79264..7234762 100644 --- a/content/docs/react-native/installation.mdx +++ b/content/docs/react-native/installation.mdx @@ -13,11 +13,26 @@ import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; { href: 'https://www.npmjs.com/package/@reclaimprotocol/inapp-rn-sdk', imgSrc: 'https://img.shields.io/npm/v/%40reclaimprotocol%2Finapp-rn-sdk.svg', alt: 'NPM Version' }, ]} /> -## Get an API Key -Setup your project using the [Get API Key guide](/api-key). +## Prerequisites +Before installing the SDK, ensure you have: + +- A [Reclaim account](https://dev.reclaimprotocol.org/explore) with an app created +- Your app credentials: app ID and app secret +- A provider ID added to your app in [Reclaim Devtools](https://dev.reclaimprotocol.org/explore) + +If you haven't set these up yet, follow the [Get API Key guide](/api-key). + +## Examples + +See complete working examples: +- [React Native Example](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/tree/main/samples/example_new_arch) - for standard React Native projects +- [Expo Example](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/tree/main/samples/example_expo) - for Expo projects + +--- # Using Expo + ## Installation ```package-install @@ -26,57 +41,60 @@ npx expo install @reclaimprotocol/inapp-rn-sdk ## Setup -Expo users can skip the native configuration changes by adding the Reclaim InApp Config Plugin. To do so merge the following code to the plugins section of your `app.json`, `app.config.js`, or `app.config.ts` file: +Add the Reclaim InApp Config Plugin to your `app.json`, `app.config.js`, or `app.config.ts`: ```diff { - // .. other plugin options (removed for brevity) "plugins": [ - "expo-router", - // Add the following in the plugins section: + "@reclaimprotocol/inapp-rn-sdk", - [ - "expo-splash-screen", - { - "image": "./assets/images/splash-icon.png", - "imageWidth": 200, - "resizeMode": "contain", - "backgroundColor": "#ffffff" - } - ] - // ... other plugins (removed for brevity) - ], - // .. other options (removed for brevity) + // ... other plugins + ] } ``` -Note: This module contains custom native code which is NOT supported by Expo Go + +This module contains custom native code and is **NOT supported by Expo Go**. You'll need to create a development build. + -If you're using Expo without EAS, run the following commands: +## Building -``` -# For iOS + + +```bash +# iOS npx expo prebuild npx expo run:ios -# For Android +# Android npx expo prebuild npx expo run:android ``` + -If you're using Expo with EAS, create a new build: - -``` -# For online builds + +```bash +# Online builds npx eas-cli build --profile development -# For local builds +# Local builds npx eas-cli build --profile development --local ``` + + + +## iOS Performance Fix +When running on iOS physical devices, add this environment variable to prevent performance issues: +1. Open your project in Xcode +2. Edit Scheme → Run → Arguments tab +3. Add environment variable: + - **Key**: `GODEBUG` + - **Value**: `asyncpreemptoff=1` -# Without using Expo +--- + +# Without Using Expo ## Installation @@ -84,32 +102,33 @@ npx eas-cli build --profile development --local npm install @reclaimprotocol/inapp-rn-sdk ``` -#### Alternative: Install from git source +Alternatively, install directly from GitHub: -```package-install +```bash npm install git+https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk.git ``` -## Setup +## Android Setup -### Android Setup +### 1. Add Activity to AndroidManifest.xml -Add the following to your `android/app/src/main/AndroidManifest.xml` file under the `` tag: +Add this inside the `` tag in `android/app/src/main/AndroidManifest.xml`: ```xml - + ``` -add the following to the end of settings.gradle: +### 2. Add Repositories + +Add these repositories to your `android/settings.gradle`: - -```groovy tabs="Groovy" +```groovy dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) String flutterStorageUrl = System.env.FLUTTER_STORAGE_BASE_URL ?: "https://storage.googleapis.com" @@ -127,171 +146,64 @@ dependencyResolutionManagement { } ``` -```kotlin tabs="Kotlin" -dependencyResolutionManagement { - repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) - val flutterStorageUrl = System.env.FLUTTER_STORAGE_BASE_URL ?: "https://storage.googleapis.com" - val reclaimStorageUrl = System.env.RECLAIM_STORAGE_BASE_URL ?: "https://reclaim-inapp-sdk.s3.ap-south-1.amazonaws.com/android/repo" - repositories { - google() - mavenCentral() - maven("$reclaimStorageUrl") - maven("$flutterStorageUrl/download.flutter.io") - } -} -``` + +If the above doesn't work, try adding the repositories to your root `build.gradle` or app-level `build.gradle` in the `allprojects` section. + - - -(Ignore if already added in `settings.gradle` from above) -or alternatively add the following repositories to the relevant repositories block: +## iOS Setup +### 1. Set Minimum iOS Version - -```groovy tabs="Groovy" -String flutterStorageUrl = System.env.FLUTTER_STORAGE_BASE_URL ?: "https://storage.googleapis.com" -String reclaimStorageUrl = System.env.RECLAIM_STORAGE_BASE_URL ?: "https://reclaim-inapp-sdk.s3.ap-south-1.amazonaws.com/android/repo" -// ... -maven { - url "$reclaimStorageUrl" -} -maven { - url "$flutterStorageUrl/download.flutter.io" -} -``` +Ensure your `ios/Podfile` has iOS 13.0 or higher: -```kotlin tabs="Kotlin" -val flutterStorageUrl = System.env.FLUTTER_STORAGE_BASE_URL ?: "https://storage.googleapis.com" -val reclaimStorageUrl = System.env.RECLAIM_STORAGE_BASE_URL ?: "https://reclaim-inapp-sdk.s3.ap-south-1.amazonaws.com/android/repo" -// ... -maven("$reclaimStorageUrl") -maven("$flutterStorageUrl/download.flutter.io") +```ruby +platform :ios, '13.0' ``` - - -### iOS Setup - -1. Make sure to have a platform declaration for your project in your `Podfile` with version 13.0 or higher. +### 2. Install Pods -```ruby -platform :ios, '13.0' # or platform :ios, min_ios_version_supported +```bash +cd ios/ +pod install ``` -Ignore if you already have this declaration in your `Podfile`. +### 3. Fix Performance on Physical Devices -2. Add the following to your `Podfile` to override SDK dependency: +Add this environment variable in your Xcode scheme to prevent performance issues on physical devices: -- This step is only required when facing issues with the resolved pod dependency. -- You can override the version of dependency when you wish to use a specific version of the SDK. -- You can add a declaration in your `Podfile` to install the SDK from cocoapods, or from a specific git tag, head, commit, or branch. +1. Open `*.xcworkspace` in Xcode +2. Edit Scheme → Run → Arguments +3. Add environment variable: + - **Key**: `GODEBUG` + - **Value**: `asyncpreemptoff=1` - -```ruby tabs="Cocoapods (Recommended)" -# Cocoapods is the recommended way to install the SDK. -pod 'ReclaimInAppSdk', '~> 0.6.0' -``` +## Advanced iOS Setup -```ruby tabs="Git Tag" -pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git', :tag => '0.6.0' -``` + + -```ruby tabs="Git Head" -pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git' -``` +If you need to use a specific version of the iOS SDK, you can override it in your `Podfile`: -```ruby tabs="Git Commit" -pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git', :commit => 'eeb5a5484a5927217065e5c988fab8201cb2db2e' +**From CocoaPods (Recommended):** +```ruby +pod 'ReclaimInAppSdk', '~> 0.18.0' ``` -```ruby tabs="Git Branch" -pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git', :branch => 'main' +**From Git Tag:** +```ruby +pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git', :tag => '0.18.0' ``` - - -- After adding the dependency, your podfile may look like this: - +**From Git HEAD:** ```ruby -platform :ios, '13.0' - -# ... some podfile content (removed for brevity) - -target 'InappRnSdkExample' do - config = use_native_modules! - - use_react_native!( - :path => config[:reactNativePath], - :app_path => "#{Pod::Config.instance.installation_root}/.." - ) - - # This is the line that you may need to add in your podfile. - pod 'ReclaimInAppSdk', '~> 0.6.0' - - pre_install do |installer| - system("cd ../../ && npx bob build --target codegen") - end - - # ... rest of the podfile. (removed for brevity) +pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git' ``` -3. Run `pod install` inside the `ios/` directory of your project. - -```sh +After adding, run: +```bash cd ios/ pod install ``` -#### Fixing performance issues on IOS physical devices - -Your app performance will be severely impacted when you run debug executable on a physical device. Fixing this requires a simple change in your Xcode project xcscheme. - - - - -1. Open your project in Xcode. -2. Click on the project target. -3. Click on the **Scheme** dropdown. - -Edit current xcscheme in Xcode - -4. Click on the **Edit Scheme** button. -5. Click on the **Run** tab. -6. Click on the **Arguments** tab and check the **Environment Variables** section. - -Enable Debug executable in Xcode - -7. Add the following environment variable: - - Key: `GODEBUG` - - Value: `asyncpreemptoff=1` -8. Click on the **Close** button in the dialog and build the project. -9. Run the app on a physical device. - - - - -This method is **not recommended** but could be useful if you don't want to add environment variables to the xcscheme. - -1. Open your project in Xcode. -2. Click on the project target. -3. Click on the **Scheme** dropdown. - -Edit current xcscheme in Xcode - -4. Click on the **Edit Scheme** button. -5. Click on the **Run** tab. -6. Uncheck the **Debug executable** checkbox. - -Enable Debug executable in Xcode - - - -## Contributing - -See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow. - -## License - -MIT \ No newline at end of file diff --git a/content/docs/react-native/usage.mdx b/content/docs/react-native/usage.mdx index 8c09a23..d89a30d 100644 --- a/content/docs/react-native/usage.mdx +++ b/content/docs/react-native/usage.mdx @@ -3,22 +3,25 @@ title: Usage description: This SDK allows Reclaim Protocol to be triggered from your app, without changing context. --- +import { Callout } from 'fumadocs-ui/components/callout'; -To use Reclaim InApp Sdk in your project, follow these steps: +## Basic Usage -1. Import the `@reclaimprotocol/inapp-rn-sdk` package in your project file. +### 1. Import the SDK ```js import { ReclaimVerification } from '@reclaimprotocol/inapp-rn-sdk'; ``` -2. Initialize the `ReclaimVerification` class to create an instance. +### 2. Initialize ```js const reclaimVerification = new ReclaimVerification(); ``` -3. Start the verification flow by providing the app id, secret and provider id. +### 3. Start Verification + +Start the verification flow with your app credentials and provider ID: ```js const verificationResult = await reclaimVerification.startVerification({ @@ -28,65 +31,217 @@ const verificationResult = await reclaimVerification.startVerification({ }); ``` -The returned result is a [ReclaimVerification.Response] object. This object contains a response that has proofs, exception, and the sessionId if the verification is successful. +The returned result is a `ReclaimVerification.Response` object containing proofs and session information. + +#### Complete Request Parameters + +```typescript +const verificationResult = await reclaimVerification.startVerification({ + // Required fields + appId: string, // Your Reclaim app ID + secret: string, // Your Reclaim app secret + providerId: string, // Provider ID from Reclaim Devtools + + // Optional fields + session?: { // Reuse existing session (SDK generates if not provided) + sessionId: string, + timestamp: string, // Milliseconds since Unix epoch + signature: string + }, + + contextString?: string, // Additional context data for verification + + parameters?: { // Custom parameters required by specific providers + [key: string]: string // Check provider details for required parameters + }, + + providerVersion?: { // Specify provider version + resolvedVersion: string, + versionExpression: string + } +}); +``` + +**Example with Optional Parameters:** + +```js +const verificationResult = await reclaimVerification.startVerification({ + appId: 'your-app-id', + secret: 'your-app-secret', + providerId: 'provider-id', + + // Add context for tracking + contextString: 'user-signup-flow', + + // Custom parameters (if required by the provider) + parameters: { + customField: 'value' + }, + + // Specify exact provider version + providerVersion: ReclaimVerification.ProviderVersion.resolved('1.0.0') +}); +``` + +## Alternative Verification Methods -### Exception Handling +### Start from URL -If the verification ends with an exception, the exception is thrown as a [ReclaimVerification.ReclaimVerificationException] object. +Start verification directly from a request URL: -Following is an example of how to handle the exception using [error.type]: +```js +const verificationResult = await reclaimVerification.startVerificationFromUrl( + 'https://api.example.com/verification-request' +); +``` + +### Start from JSON Template + +Start verification using a JSON template: + +```js +const template = { + appId: 'your-app-id', + secret: 'your-app-secret', + providerId: 'provider-id', + // ... other configuration +}; + +const verificationResult = await reclaimVerification.startVerificationFromJson(template); +``` + +## Exception Handling + +If verification fails or is interrupted, a `ReclaimVerificationException` is thrown. Handle different exception types: ```js try { - // ... start verification + const result = await reclaimVerification.startVerification({ + appId: config.REACT_APP_RECLAIM_APP_ID, + secret: config.REACT_APP_RECLAIM_APP_SECRET, + providerId: providerId, + }); + + // Verification successful + console.log('Proofs:', result.proofs); + } catch (error) { if (error instanceof ReclaimVerification.ReclaimVerificationException) { + switch (error.type) { case ReclaimVerification.ExceptionType.Cancelled: - Snackbar.show({ - text: 'Verification cancelled', - duration: Snackbar.LENGTH_LONG, - }); + console.log('User cancelled verification'); break; + case ReclaimVerification.ExceptionType.Dismissed: - Snackbar.show({ - text: 'Verification dismissed', - duration: Snackbar.LENGTH_LONG, - }); + console.log('Verification was dismissed'); break; + case ReclaimVerification.ExceptionType.SessionExpired: - Snackbar.show({ - text: 'Verification session expired', - duration: Snackbar.LENGTH_LONG, - }); + console.log('Verification session expired'); break; + case ReclaimVerification.ExceptionType.Failed: default: - Snackbar.show({ - text: 'Verification failed', - duration: Snackbar.LENGTH_LONG, - }); + console.log('Verification failed:', error.reason); + break; } + + // Access additional error details + console.log('Session ID:', error.sessionId); + console.log('Reason:', error.reason); + console.log('Inner Error:', error.innerError); + } else { - Snackbar.show({ - text: error instanceof Error ? error.message : 'An unknown verification error occurred', - duration: Snackbar.LENGTH_LONG, - }); + console.error('Unexpected error:', error); } } ``` -This error also contains `sessionId`, `reason`, and `innerError` that can be used to get more details about the occurred error. +## Advanced Usage + +### Customize Verification Flow + +Override SDK configuration to customize the verification experience: ```js -error.sessionId -error.reason -error.innerError +reclaimVerification.setOverrides({ + appInfo: { + appName: "My Custom App", + appImageUrl: "https://example.com/logo.png" + }, + // ... other override options +}); ``` -## Migration +For detailed override options, see the [SDK documentation](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/overrides.md). + +### Clear All Overrides + +Reset all customizations to defaults: + +```js +reclaimVerification.clearAllOverrides(); +``` + +### Set Verification Options + +Configure additional verification options: + +```js +reclaimVerification.setVerificationOptions({ + // ... options +}); +``` -- Migration steps for [0.3.1](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#031) -- Migration steps for [0.3.0](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#030) -- Migration steps for [0.2.1](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#021) +## Troubleshooting + +### Cronet Errors on Android + +On Android devices without Google Play Services, you may see Cronet-related errors. Add this dependency to your `android/build.gradle`: + +```gradle +dependencies { + // ... other dependencies + implementation("org.chromium.net:cronet-embedded:119.6045.31") +} +``` + +### expo-dev-client Incompatibility (iOS) + +There's a known incompatibility between `ReclaimInAppSdk` and `expo-dev-client` on iOS that causes network request timeouts. Temporarily remove `expo-dev-client` when testing Reclaim functionality on iOS. + +### iOS Build Issues + +If you encounter CocoaPods compatibility errors: + +```bash +cd ios/ +pod update ReclaimInAppSdk +``` + +### Build Failures (0.7.x versions) + +Versions 0.7.0-0.7.2 have build issues. Update to 0.7.3 or later: + +```bash +npm install @reclaimprotocol/inapp-rn-sdk@latest +``` + +## Migration +When upgrading to newer versions, follow the migration guides: + +- [0.15.0](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#0150) +- [0.12.0](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#0120) +- [0.10.11](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#01011) +- [0.9.2](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#092) +- [0.9.1](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#091) +- [0.9.0](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#090) +- [0.8.3](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#083) +- [0.7.3](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#073) +- [0.6.0](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/documentation/migration.md#060) + + +For the latest updates and features, check the [SDK changelog](https://github.com/reclaimprotocol/reclaim-inapp-reactnative-sdk/blob/main/CHANGELOG.md). +