iOS SDK

This guide will help you integrate Verisoul into your native iOS apps, configure it, retrieve a session ID, handle errors, and meet privacy compliance requirements.

See iOS Example App for a comprehensive example app

In This Guide, You Will Learn How To:

Include the SDK: Add VerisoulSDK to your iOS project using CocoaPods or Swift Package Manager (SPM).
Configure the SDK: Initialize the SDK with your environment and project identifier.
Retrieve a Session ID: Obtain a unique session identifier to validate user authenticity.
Optionally Enable Device Check and App Attest: Provide the necessary Apple credentials if you choose to toggle these features on.
Handle Errors: Implement basic error handling for robust integration.
Privacy Compliance: Declare your app’s privacy practices using a privacy manifest file.

Prerequisites

Xcode: Version 15.0 or higher.
iOS Deployment Target: iOS 14.0 or higher
App Attest Capability:
To fully utilize VerisoulSDK, your app must include the App Attest capability. Update your app’s entitlements file with the following key:
```
<key>com.apple.developer.devicecheck.appattest-environment</key>
<string>production</string>
```
Replace production with development if needed. Production most be used in deployed applications.

Including the SDK in Your App

You can integrate VerisoulSDK into your project using CocoaPods or Swift Package Manager (SPM).

CocoaPods

Install CocoaPods (if you haven’t already):
```
sudo gem install cocoapods
```
Update Your Podfile to include VerisoulSDK:
```
pod 'VerisoulSDK', '~> 0.2.5'
```
Install the Pod:
```
pod install
```
Open Your Workspace:
Launch the generated .xcworkspace file in Xcode.

Swift Package Manager (SPM)

Open Your Project in Xcode.
Navigate to File > Add Packages.
Enter the Repository URL:
```
https://github.com/verisoul/ios-sdk.git
```
Select the Version:
Choose the version you wish to use and add the package to your project.

Configuring the SDK

Before using any features of VerisoulSDK, you need to configure it with your environment and unique project identifier. This is typically done in your AppDelegate or SceneDelegate. It is important to call .configure() as early as possible in the application lifecycle to prevent any user friction.

Example: Configure VerisoulSDK

import VerisoulSDK

// Initialize the SDK during app launch
Verisoul.shared.configure(env: .prod, projectId: "your-project-id")

Notes:

The env parameter accepts values such as .sandbox or .prod based on your deployment stage.
- The environment must match the project_id. Different environments have different project_id's.
Ensure this configuration is called only once during the app's initialization.

Retrieving a Session ID

VerisoulSDK offers an asynchronous method to retrieve a session ID. You can get a session_id at any point in your application. VerisoulSDK starts processing as soon as .configure() is called and releases the session_id when it is complete. If the data collection has already completed when .session() is called the function will return immediately.

Example: Retrieve Session ID

import VerisoulSDK

Task {
    do {
        let sessionId = try await Verisoul.shared.session()
        print("Session ID: \(sessionId)")
    } catch {
        print("Error retrieving session ID: \(error.localizedDescription)")
    }
}

The session ID should be passed to your backend and used to securely call the Verisoul API.

Details on the backend API flow can be found here https://docs.verisoul.ai/docs/authenticate-session

Device Check and App Attest Integration

VerisoulSDK collects device and network risk data and wraps Apple’s Device Check and App Attest APIs to improve security. These features are optional — you can choose to enable or disable them as needed.

To enable these features, you must provide the following information in the developer section of the Verisoul dashboard:

Apple Team ID: Your Apple Developer Team identifier.
Bundle Identifier: The bundle ID of your app.
Device Check Private Key: Create a private key (a .p8 file) and provide its associated Key ID.
- Create the Device Check Key here https://developer.apple.com/account/resources/authkeys/list
- Sharing this key only allow Verisoul to validate device check tokens created by your application https://developer.apple.com/documentation/devicecheck

Input these credentials into the Verisoul dashboard to toggle Device Check and App Attest on. If you choose not to enable these features, the SDK will still function by collecting device and network risk data.

Error Handling

If the session retrieval process fails (for example, if the device is offline), VerisoulSDK throws an error.

We recommend not letting a user proceed past a "critical event" in your application without having a session_id to balance security and user experience. Typical "critical events" include signup, a monetary transaction or any point in your application flow where a fraudulent user can extract value.

Privacy Manifest Files

Starting in Spring 2024, Apple requires that developers declare the reasons for using certain APIs (the Required Reason APIs) through privacy manifest files. These files help describe your app’s or SDK’s data practices, including:

Data Collection & Purpose: What data is collected (e.g., Device ID) and for what purpose (e.g., preventing fraud).
Required Reason APIs: The APIs your SDK uses and why — helping Apple and your users understand your privacy practices.

For Verisoul Fraud Prevention SDK, the privacy manifest file declares:

NSPrivacyTracking:
Set to false since the SDK does not use collected data for tracking.
NSPrivacyTrackingDomains:
An empty array, as the SDK does not interact with any tracking domains.
NSPrivacyCollectedDataTypes:
Specifies that the only data collected is the Device ID (IDFV), which is used solely for app functionality (fraud prevention) and is not linked to a user’s identity or used for tracking.
NSPrivacyAccessedAPITypes:
Lists the required API(s) used by the SDK. For instance, the System Boot Time APIs are used to measure elapsed time between SDK events.

Sample Privacy Manifest File for Verisoul Fraud Prevention SDK

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<!--
   PrivacyInfo.xcprivacy
   Verisoul Fraud Prevention SDK for iOS
   Created by [Your Name] on [Date].
   Copyright (c) 2025 ___ORGANIZATIONNAME___.
-->
<plist version="1.0">
<dict>
    <!-- Indicates that no tracking data is collected -->
    <key>NSPrivacyTracking</key>
    <false/>

    <!-- No Internet domains are used for tracking -->
    <key>NSPrivacyTrackingDomains</key>
    <array/>

    <!-- Details the collected data type (Device ID) -->
    <key>NSPrivacyCollectedDataTypes</key>
    <array>
      <dict>
        <key>NSPrivacyCollectedDataType</key>
        <string>NSPrivacyCollectedDataTypeDeviceID</string>
        <key>NSPrivacyCollectedDataTypeLinked</key>
        <false/>
        <key>NSPrivacyCollectedDataTypeTracking</key>
        <false/>
        <key>NSPrivacyCollectedDataTypePurposes</key>
        <array>
          <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
        </array>
      </dict>
    </array>

    <!-- Declares the Required Reason API used (System Boot Time APIs) -->
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
      <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>35F9.1</string>
        </array>
      </dict>
    </array>
</dict>
</plist>

Happy integrating!