diff --git a/content/docs/ios-swift/installation.mdx b/content/docs/ios-swift/installation.mdx index ecc7ebc..503e37d 100644 --- a/content/docs/ios-swift/installation.mdx +++ b/content/docs/ios-swift/installation.mdx @@ -5,212 +5,71 @@ description: Integrate Reclaim Protocol into iOS Native Applications. import { BadgeGroup } from '@/app/components/badge'; import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; -import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; ## Prerequisites -- An iOS application source code (Support for iOS 13 or later). -- An iOS device running iOS 13 or later. -- A Reclaim account where you've created an app and have the app id, app secret. -- A provider id that you've added to your app in Reclaim Devtools. +- iOS 14.0+ application +- [Reclaim account](https://dev.reclaimprotocol.org/explore) with app ID, app secret, and provider ID ([Get API Key guide](/api-key)) -## Get an API Key -Setup your project using the [Get API Key guide](/api-key). +## Examples +- [SwiftUI Example](https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk/tree/main/Examples/SwiftUIExample) +- [SwiftUI with CocoaPods](https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk/tree/main/Examples/SwiftUIWithPodExample) ## Installation -### 1. Adding Reclaim InApp SDK to your Xcode Project +### Swift Package Manager (Recommended) - - +1. In Xcode: **File** → **Add Package Dependency** +2. Enter URL: `https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git` +3. Click **Add Package** and select your app target -Copy the following URL and use it to add Swift Package Manager (SPM) dependency into the Xcode project: +### CocoaPods -``` -https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git -``` - -#### How to add a Swift Package Manager (SPM) dependency to your Xcode project: - -1. In your Xcode Editor's toolbar, click on `File` > `Add Package Dependency...`. -Add a dependency to your Xcode project -2. In the `Add Package Dependency` dialog box, paste the URL `https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git` into the `Search or Enter package URL` field on the top right corner of dialog box. -Add a dependency to your Xcode project -3. Click `Add Package`. -4. In the other window, select your **app target** in the `Add to Targets` section and then click `Add package`. -Add a dependency to your Xcode project - -This should complete the installation of the Reclaim InApp SDK. Now follow the [steps below to link the necessary frameworks to your Xcode project](#2-add-reclaims-xcframeworks-to-your-xcode-project). - -##### Note - -- It's worth noting that you should commit the **swiftpm** folder that will be built and more specifically that the **Package.resolved** file should be included in your source control/git. - - - - - -1. Make sure to define a global platform for your project in your `Podfile` with version 13.0 or higher. +Add to your `Podfile`: + + ```ruby -platform :ios, '13.0' -``` - -2. Add the following to your `Podfile` to override the default version of the ReclaimInAppSdk (optional): - - - - -```ruby tabs="From Cocoapods (recommended)" -pod 'ReclaimInAppSdk' '~> 0.3.0' -``` +platform :ios, '14.0' -```ruby tabs="From a specific tag" -pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git', :tag => '0.3.0' +pod 'ReclaimInAppSdk', '~> 0.21.1' ``` + -```ruby tabs="From git HEAD" -pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git' -``` - -```ruby tabs="From a specific commit" -pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git', :commit => '027e18b8b2365fd935e9e8585e31fa886c3af6ee' -``` - -```ruby tabs="From a specific branch" -pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git', :branch => 'main' -``` - - - -2. After adding the dependency, your podfile may look like this: - + ```ruby -platform :ios, '13.0' - -target 'GitPodSwiftUIExample' do - # Comment the next line if you don't want to use dynamic frameworks - use_frameworks! - - # Pods for GitPodSwiftUIExample - pod 'ReclaimInAppSdk', '~> 0.3.0' +platform :ios, '14.0' - target 'GitPodSwiftUIExampleTests' do - inherit! :search_paths - # Pods for testing - end - - target 'GitPodSwiftUIExampleUITests' do - # Pods for testing - end - -end +pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git', :tag => '0.21.1' ``` + -3. Run `pod install`. -4. Open the `*.xcworkspace` file to work on the project. Verify that you're opening MyApp.xcworkspace and not opening MyApp.xcodeproj. The .xcworkspace file has the CocoaPod dependencies, the .xcodeproj doesn't. - -For more info, check the [Reclaim Example - SwiftUI with CocoaPods](https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk/blob/main/Examples/SwiftUIWithPodExample/README.md) for a complete example of how to use the SDK in a SwiftUI application with CocoaPods. - - - - - - - - -```swift tabs="version" -.package(url: "https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git", from: "0.3.0") -``` + +```ruby +platform :ios, '14.0' -```swift tabs="branch" -.package(url: "https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git", branch: "main") +pod 'ReclaimInAppSdk', :git => 'https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk.git' ``` - + -#### Select a product: - -- ReclaimInAppSdk - -```swift -.product(name: "ReclaimInAppSdk", package: "reclaim-inapp-ios-sdk") -``` - - - - - -#### Build the project. - -1. If you have a `*.xcworkspace` then open `YourApp.xcworkspace` in Xcode. Verify that you're opening MyApp.xcworkspace and not opening MyApp.xcodeproj. The .xcworkspace file has the CocoaPod dependencies, the .xcodeproj doesn't. If you don't have a `*.xcworkspace` then open `YourApp.xcodeproj` in Xcode. -2. Select **Product** > **Build** or press `Cmd + B`. - - - - -1. Your build may fail due to an error like this: - -Xcode build error due to CocoaPods - -2. To fix this, open the `*.xcworkspace` file in Xcode. In your target's `Build Settings`, under `Build Options` Section, set `User Script Sandboxing` to `No` and build the project again. - -Xcode build error due to CocoaPods - - - - -### 2. Fixing performance issues - -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. +Run `pod install` and open the `.xcworkspace` file. -Edit current xcscheme in Xcode +**Troubleshooting**: If build fails, set **User Script Sandboxing** to **No** in Build Settings → Build Options. -4. Click on the **Edit Scheme** button. -5. Click on the **Run** tab. -6. Uncheck the **Debug executable** checkbox. +## Performance Fix -Enable Debug executable in Xcode +To prevent performance issues on physical devices, add this environment variable: - - +1. Edit Scheme → Run → Arguments +2. Add environment variable: + - **Key**: `GODEBUG` + - **Value**: `asyncpreemptoff=1` diff --git a/content/docs/ios-swift/usage.mdx b/content/docs/ios-swift/usage.mdx index 5dbbcba..ef0b587 100644 --- a/content/docs/ios-swift/usage.mdx +++ b/content/docs/ios-swift/usage.mdx @@ -1,94 +1,104 @@ --- title: Usage -description: Reclaim Protocol's InApp iOS SDK for ZK proof generations for requests with an in-app experience of web verification +description: Reclaim Protocol's InApp iOS SDK for ZK proof generation with in-app web verification --- +## Basic Usage -### Use ReclaimInAppSdk in your project - -To use ReclaimInAppSdk in your project, follow these steps: - -1. Import the ReclaimInAppSdk module into your Swift file. +### 1. Import the SDK ```swift import ReclaimInAppSdk ``` -2. Create a request object. +### 2. Create Request ```swift let request = ReclaimVerification.Request.params( try .init( - /// You can use the appId and secret from Reclaim Devtools to create a request. - /// Providing appId and secret here in this initializer is optional. - /// If you don't provide it, the SDK will use the appId and secret from the Info.plist file. - // appId: "YOUR_APP_ID_FROM_RECLAIM_DEVTOOLS", - // secret: "YOUR_APP_SECRET_FROM_RECLAIM_DEVTOOLS", - /// This is the provider id that you've added to your app in Reclaim Devtools. - /// The verification flow will use the provider information fetch by this provider id. - providerId: providerId + // Optional: defaults to Info.plist if not provided + // appId: "YOUR_APP_ID", + // secret: "YOUR_APP_SECRET", + providerId: "YOUR_PROVIDER_ID" ) ) ``` -More ways to create a request object are available in the `ReclaimVerification.Request.*` apis. - -3. Start the verification flow. +### 3. Start Verification ```swift -// This is the function that starts the verification flow. -// This may fail if device screen is getting shared. -let result = try await ReclaimVerification.startVerification(request) -``` +do { + let result = try await ReclaimVerification.startVerification(request) -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. + // Verification successful + print("Proofs:", result.response.proofs) + print("Session ID:", result.response.sessionId) -If the verification is cancelled or failed, the result will contain an exception. +} catch ReclaimVerificationError.cancelled { + print("User cancelled") +} catch ReclaimVerificationError.dismissed { + print("Verification dismissed") +} catch ReclaimVerificationError.sessionExpired { + print("Session expired") +} catch ReclaimVerificationError.failed(let error) { + print("Failed:", error) +} catch { + print("Unexpected error:", error) +} +``` -You can use the `ReclaimVerification.Response` object to get the proof, exception, and sessionId. +## Complete Request Parameters ```swift -let proof = result.response.proofs -let exception = result.response.exception -let sessionId = result.response.sessionId -``` - -If the verification is successful, the proof will contain the data that you need to store in your database. +let request = ReclaimVerification.Request.params( + try .init( + // Required + providerId: "YOUR_PROVIDER_ID", -If the verification is cancelled or failed, the exception will contain the error details. + // Optional + appId: "YOUR_APP_ID", // Defaults to Info.plist + secret: "YOUR_APP_SECRET", // Defaults to Info.plist -In the above apis, `ReclaimVerification.Request.*`, `ReclaimVerification.startVerification` or `ReclaimVerification.startVerificationFromUrl` can also throw an error. The error can be one of the following: + session: .init( // Reuse existing session + timestamp: "1234567890", + sessionId: "session-id", + signature: "signature" + ), -- `ReclaimVerificationError.cancelled`: The verification was cancelled by the user. -- `ReclaimVerificationError.dismissed`: The verification was dismissed by the sdk. -- `ReclaimVerificationError.failed(let error)`: The verification failed due to an error. -- `ReclaimVerificationError.sessionExpired`: The verification session expired. + contextString: "additional-context", // Additional context data -You can handle the error by using a `do-catch` block. For example: + parameters: [ // Custom provider parameters + "customParam": "value" + ], -```swift -do { - let result = try await ReclaimVerification.startVerification(request) -} catch ReclaimVerificationError.cancelled { - print("Verification cancelled") -} catch ReclaimVerificationError.dismissed { - print("Verification dismissed") -} + providerVersion: .init( // Specify provider version + resolvedVersion: "1.0.0", + versionExpression: "1.0.0" + ) + ) +) ``` -For a complete example, see the [Reclaim Example - SwiftUI](https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk/blob/53a19f88c8d90df485a60dc20190f740cd9fd108/Examples/SwiftUIExample/SwiftUIExample/ContentView.swift). - -## Example +## Alternative Methods -- See the [Reclaim Example - SwiftUI](https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk/blob/53a19f88c8d90df485a60dc20190f740cd9fd108/Examples/SwiftUIExample/README.md) for a complete example of how to use the SDK in a SwiftUI application. -- See the [Reclaim Example - SwiftUI with CocoaPods](https://github.com/reclaimprotocol/reclaim-inapp-ios-sdk/blob/main/Examples/SwiftUIWithPodExample/README.md) for a complete example of how to use the SDK in a SwiftUI application with CocoaPods. +### Start from URL +```swift +let result = try await ReclaimVerification.startVerificationFromUrl( + "https://api.example.com/verification-request" +) +``` -## Upgrading - -To upgrade to a new version of the Reclaim InApp SDK, follow these steps: +## Advanced Usage -1. Make sure you have the latest version of the Reclaim InApp SDK. Currently the latest version is `v0.3.0`. -1. Incase of any problems: remove package, clear build, restart Xcode, and add package again. +### Customize Verification Flow -Migration guides will be available when a new version with API changes is released. \ No newline at end of file +```swift +try await ReclaimVerification.setOverrides( + appInfo: ReclaimOverrides.ReclaimAppInfo( + appName: "My Custom App", + appImageUrl: "https://example.com/logo.png" + ) + // Add other overrides as needed +) +```