> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verisoul.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS

> Integrating Verisoul in iOS Apps

*To run the SDK a Verisoul Project ID is required.* Schedule a call [here](https://meetings.hubspot.com/henry-legard) to get started.

## System Requirements

* iOS 14.0 or higher
* Xcode 15.0 or higher
* Swift 5.9 or higher
* CocoaPods 1.10+ (if using CocoaPods)
* SDK Size: \~480 KB

## Installation

You can install VerisoulSDK in your iOS project using either CocoaPods or Swift Package Manager.

### CocoaPods

To integrate VerisoulSDK with CocoaPods:

1. Ensure CocoaPods is installed on your machine. If not, run:
   ```sh theme={null}
   sudo gem install cocoapods
   ```
2. Add VerisoulSDK to your Podfile:
   ```ruby theme={null}
   pod 'VerisoulSDK', '~> 0.4.66'
   ```
3. Run the following command to install the SDK:
   ```sh theme={null}
   pod install
   ```
4. Open the `.xcworkspace` file in Xcode and start using the SDK.

### Swift Package Manager (SPM)

To integrate VerisoulSDK using Swift Package Manager:

1. Open your project in Xcode.
2. Go to `File > Add Packages`.
3. Enter the repository URL for VerisoulSDK:
   ```url theme={null}
   https://github.com/verisoul/ios-sdk.git
   ```
4. Choose the version you wish to use and add the package.

The SDK will automatically integrate into your project.

### iOS Device Check

To fully utilize the Verisoul SDK, you must add the `App Attest` capability to your project. This capability allows the SDK to perform necessary checks and validations to ensure the integrity and security of your application.

Update your app's entitlements file:

```xml theme={null}
<key>com.apple.developer.devicecheck.appattest-environment</key>
<string>production</string>  <!-- Use 'development' for testing -->
```

## Usage

### Initialize the SDK

Call `configure()` when your application starts, typically in `AppDelegate` or the main app entry point.

```swift theme={null}
import VerisoulSDK

Verisoul.shared.configure(env: .prod, projectId: "your-project-id")
```

The `configure()` method initializes the Verisoul SDK with your project credentials. This method must be called once when your application starts.

**Parameters:**

* `env`: The environment to use `.prod` for production or `.sandbox` for testing
* `projectId`: Your unique Verisoul project identifier

### Get Session ID

The `session()` method returns the current session identifier after the SDK has collected sufficient device data. This session ID is required to request a risk assessment from Verisoul's API.

**Important Notes:**

* Session IDs are short-lived and expire after 24 hours
* The session ID becomes available once minimum data collection is complete (typically within seconds)
* You should send this session ID to your backend, which can then call Verisoul's API to get a risk assessment

**Example:**

```swift theme={null}
do {
    let sessionId = try await Verisoul.shared.session()
    // Send sessionId to your backend for risk assessment
    print("Session ID: \(sessionId)")
} catch {
    print("Failed to retrieve session ID: \(error)")
}
```

### Provide Touch Events

The Verisoul SDK automatically captures touch events when integrated. No additional code is required for touch event collection.

### Error Codes

The SDK throws `VerisoulException` with the following error codes:

| Error Code           | Description                                                                                                                                                | Recommended Action                                                                                       |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| INVALID\_ENVIRONMENT | The environment parameter passed to `Verisoul.init()` is invalid. Valid values are "dev", "sandbox", or "prod".                                            | Ensure the environment parameter is exactly "dev", "sandbox", or "prod" (case-sensitive, no whitespace). |
| SESSION\_UNAVAILABLE | A valid session ID could not be obtained. This typically occurs when Verisoul's servers are unreachable due to network blocking or a very slow connection. | Implement exponential backoff. Prompt user to check network or disable network blocker.                  |
| WEBVIEW\_UNAVAILABLE | WebView is not available on the device. This can occur when WebView is disabled, missing, uninstalled, or corrupted on the device.                         | Prompt user to enable WebView in settings, update Android System WebView, or switch devices.             |

#### Exception Structure

All errors are thrown as `VerisoulException` with the following properties:

| Property | Type       | Description                                             |
| -------- | ---------- | ------------------------------------------------------- |
| code     | String     | One of the error codes above                            |
| message  | String     | Human-readable error description                        |
| cause    | Throwable? | The underlying exception that caused the error (if any) |

## Example

For a complete working example, see the [iOS Sample App](/examples/ios-sample-app).

## Additional Resource

* [Verisoul CocoaPods](https://cocoapods.org/pods/VerisoulSDK)