iOS

The SDK requires iOS 15.0+ at runtime (deployment target 13.0+). Calls are guarded with @available(iOS 15.0, *) and are no-ops below iOS 15.

Prerequisites

iOS 15.0 or higher at runtime
App ID, Client ID, and Client Secret from the OTPless dashboard
Swift 5.5–6.0, Xcode 14+

Installation

Swift Package Manager Add the package URL in Xcode → File → Add Package Dependencies…, or in your Package.swift:

https://github.com/otpless-tech/otpless-ios-intelligence-sdk

Dependency rule: Up to Next Major Version from 1.2.0. CocoaPods

Podfile

platform :ios, '13.0'
use_frameworks!
pod 'OTPlessIntelligence', '~> 1.2.0'

Run pod install and open the generated .xcworkspace. OtplessEventIO is resolved transitively — no manual step.

Add permissions

In your Info.plist, add the optional permissions:

Info.plist

<!-- Optional: enables GPS / geo-spoof signals -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to detect location spoofing and protect your account.</string>

Optional entitlements that improve signal accuracy (Signing & Capabilities → + Capability):

Access WiFi Information — network identity signals.
iCloud → CloudKit — cross-device identity signals.

The SDK never requests location itself. If geo signals matter, prompt the user before your first fetchIntelligence:

import CoreLocation

CLLocationManager().requestWhenInUseAuthorization()

Initialize the SDK

Call initialize once, as early as possible — in your AppDelegate or SwiftUI @main init(). Pass your App ID:

AppDelegate.swift

import OTPlessIntelligence

if #available(iOS 15.0, *) {
    OTPlessIntelligence.shared.initialize(appId: "<OTPLESS_APP_ID>") { success in
        // true  → SDK ready
        // false → check [OTPless] logs (debug builds only)
    }
}

isInitialized: Bool reflects whether initialize has completed successfully.

Integrate with OtplessBM SDK

If you already use OtplessBM, you do not call fetchIntelligence yourself — set deviceFingerprintMode on the request and OtplessBM handles the fetch via runtime lookup. You still install OTPlessIntelligence and call initialize(appId:) at launch.

import OtplessBM

let otplessRequest = OtplessRequest()
otplessRequest.set(phoneNumber: "PHONE_NUMBER", countryCode: "COUNTRY_CODE")
otplessRequest.set(deviceFingerprintMode: .SYNC)
Otpless.shared.startHeadless(withRequest: otplessRequest, ...)

`DeviceFingerprintMode` values

Value	Behaviour
`NONE`	Device fingerprinting is disabled. Default value.
`ASYNC`	Fingerprint is collected in parallel with the auth request. Does not add latency.
`SYNC`	Fingerprint is collected before the auth request is sent. Ensures fingerprint data is always included.

If OTPlessIntelligence is not linked or not initialized, OtplessBM logs a warning and the auth flow proceeds without a dfrId — failures never block auth.

Fetch device intelligence

fetchIntelligence returns an IntelligenceApiResponse containing dfrId. Call it from a Task (async form) or via the ObjC-bridged callback.

import OTPlessIntelligence

Task {
    do {
        let response = try await OTPlessIntelligence.shared.fetchIntelligence()
        // Send response.dfrId to your backend to fetch the full report.
    } catch {
        // Handle the error — degrade gracefully.
    }
}

Callback form (Swift or Objective-C):

OTPlessIntelligence.shared.fetchIntelligence(params: nil, updateInfo: nil) {
    success, dfrId, intelligenceResponse, errorMessage in
    DispatchQueue.main.async {
        // Completion fires on a background thread.
    }
}

Retries: the engine call and backend push both use exponential backoff — 500 ms base, max 4 attempts. A response missing dfrId is treated as a failure and retried.

Pass additional context (optional)

Pass params and/or updateInfo to attach extra context and enable more accurate risk scoring.

let updateInfo = UpdateInfo(
    userId: "user-123",
    phoneNumber: "1234567890",
    phoneInputType: .manual,
    otpInputType: .autoFilled,
    userEventType: .transaction,
    merchantId: "merchant-id",
    additionalInput: [
        "TRANSACTION_ID": "txn-abc-123",
        "METHOD": "UPI",
        "AMOUNT": "500",
        "CURRENCY": "INR"
    ]
)

let response = try await OTPlessIntelligence.shared.fetchIntelligence(updateInfo: updateInfo)

In the callback / Objective-C form, updateInfo is a dictionary; enum fields expect raw-value strings ("MANUAL", "COPY_PASTED", "LOGIN", …). Unknown keys and invalid enum strings are silently dropped.

`UpdateInfo` fields

Field	Type	Description
`userId`	`String?`	Your internal user identifier. Used to correlate the result with a user account.
`phoneNumber`	`String?`	Customer phone number.
`phoneInputType`	`PhoneInputType?`	How the phone number was entered: `.manual`, `.copyPasted`, `.googleHint`.
`otpInputType`	`OtpInputType?`	How the OTP was entered: `.manual`, `.copyPasted`, `.autoFilled`.
`userEventType`	`UserEventType?`	The action being performed: `.login`, `.signup`, `.transaction`, `.others`.
`merchantId`	`String?`	Merchant identifier, if applicable.
`additionalInput`	`[String: String]?`	Arbitrary key-value pairs for custom context.

params is a per-call pass-through — every non-reserved entry is forwarded into the push body verbatim. Reserved keys (silently dropped): data, status, requestId, message, plus SDK-set tsId, inId, platform, appId.

Get the detailed report (server-side)

After receiving dfrId, your backend exchanges it for the full report. Never call this from the app — it requires CLIENT_SECRET.

curl --request POST \
  --url https://platform.otpless.app/client/v1/device-fingerprint \
  --header 'clientid: YOUR_CLIENT_ID' \
  --header 'clientsecret: YOUR_CLIENT_SECRET' \
  --header 'content-type: application/json' \
  --data '{ "dfrId": "DFRID_FROM_SDK", "deviceType": "IOS" }'

Sample response

Success

{
    "requestId": "403ad427-5018-47b9-b6e8-790e17a78201",
    "sessionId": "233sd769-9367-39h9-b9e8-650eb6e87820",
    "newDevice": false,
    "deviceId": "43fccb70-d64a-4c32-a251-f07c082d7034",
    "vpn": false,
    "proxy": false,
    "simulator": false,
    "jailbroken": false,
    "cloned": false,
    "geoSpoofed": false,
    "mirroredScreen": false,
    "hooking": false,
    "appTampering": false,
    "factoryReset": false,
    "factoryResetTime": 1743419662000,
    "ip": "106.219.161.71",
    "sessionRiskScore": 0.0,
    "deviceRiskScore": 0.0,
    "gpsLocation": { "latitude": 28.51, "longitude": 77.08, "altitude": 237.24 },
    "ipDetails": {
        "city": "New Delhi",
        "region": "National Capital Territory of Delhi",
        "country": "IN",
        "isp": "Reliance Jio Infocomm Limited",
        "asn": "55836",
        "fraudScore": 0.0
    },
    "deviceMeta": {
        "brand": "Apple",
        "model": "iPhone15,2",
        "iOSVersion": "17.4.1",
        "cpuType": "arm64",
        "screenResolution": "1179x2556",
        "totalRAM": "5368709120",
        "storageAvailable": "58363809792",
        "storageTotal": "113598214144"
    },
    "ruleAction": {
        "action": "WARN",
        "name": "VPN enabled",
        "description": "A VPN connection was detected on this device.",
        "message": "For security reasons, please disable your VPN and try again."
    },
    "appliedRules": {
        "rules": { "55 : VPN enabled": 0, "99 : App is tampered": 50 },
        "totalScore": 50.0
    },
    "additionalData": {}
}

Error

{
  "requestId": "7e12d131-2d90-4529-a5c7-35f457d86ae6",
  "errorMessage": "OTPless server error"
}

Response fields

Field	Type	Description	Default
`requestId`	string	Unique identifier for the request.	`""`
`sessionId`	string	Unique identifier for the current app session.	`""`
`newDevice`	boolean	Whether this is the first time this device has been seen.	`false`
`deviceId`	string	Stable identifier for the device.	`""`
`sessionRiskScore`	float	Risk score (0–100) based on the current session state.	`0.0`
`deviceRiskScore`	float	Risk score that also factors in the device’s historical state across past sessions.	`0.0`
`vpn`	boolean	A VPN is active on the device.	`false`
`proxy`	boolean	The device is behind a proxy server.	`false`
`simulator`	boolean	The app is running on a simulator rather than physical hardware.	`false`
`jailbroken`	boolean	The device has been jailbroken.	`false`
`cloned`	boolean	The user is running a cloned instance of the app.	`false`
`geoSpoofed`	boolean	The device’s location is being faked.	`false`
`mirroredScreen`	boolean	The device’s screen is being mirrored.	`false`
`hooking`	boolean	The app has been altered by a hooking framework.	`false`
`appTampering`	boolean	The app binary has been modified in an unauthorized way.	`false`
`factoryReset`	boolean	A suspicious factory reset has been performed.	`false`
`factoryResetTime`	long	Timestamp of the last factory reset. `-1` if not detected.	`-1`
`ip`	string	Current IP address of the device.	`""`
`ipDetails`	object	IP metadata including country, region, city, ISP, ASN, and fraud score.	`{}`
`gpsLocation`	object	GPS location details including latitude, longitude, and altitude.	`{}`
`deviceMeta`	object	Device hardware metadata: brand, model, OS version, screen resolution, storage, RAM, CPU.	`{}`
`ruleAction`	object	The triggered rule and recommended action (`ALLOW`, `WARN`, `BLOCK`) with a user-facing message.	`{}`
`appliedRules`	object	Full list of evaluated rules, their scores, and the total rule score.	`{}`
`additionalData`	object	Reserved for custom fields returned based on your account configuration.	`{}`

Error reference

public enum OTPlessIntelligenceError: Error {
    case notConfigured
    case intelligenceError(requestId: String, message: String)
    case unknown
}

Case (async)	Callback `errorMessage`	When it fires
`.notConfigured`	`"SDK not initialised"`	`fetchIntelligence` called before `initialize` succeeded
`.intelligenceError(requestId:message:)`	server-provided message	Engine error, push failure, or `dfrId` missing after all retries
`.unknown`	`"Unknown intelligence error"`	Unexpected internal state

Intelligence signals are advisory — always degrade gracefully on failure. Log requestId for support.

Troubleshooting

initialize returns false — check [OTPless] logs in debug builds. Common causes: invalid App ID (401), App ID not found (404), no internet, or credentials rejected by IdentityFraud.
fetchIntelligence returns .notConfigured — you called it before initialize completed. Wait for the completion callback with success == true.
No such module 'OTPlessIntelligence' — CocoaPods: open .xcworkspace, re-run pod install. SPM: File → Packages → Resolve Package Versions. Then Clean Build Folder (⇧⌘K).
With OtplessBM, dfrId never arrives — confirm OTPlessIntelligence is linked and initialize(appId:) runs before any OtplessBM request with mode .SYNC / .ASYNC. Look for OTPLESS: OTPlessIntelligence not linked. in the device log.
UI crash after fetchIntelligence — completions fire on a background thread; wrap UI updates in DispatchQueue.main.async.
Simulator — some signals (GPS, IP, hardware attestation) are unavailable or mocked. Validate on a real device before release.

Device Fingerprint

SDK

Backend API

Prerequisites

Installation

Add permissions

Initialize the SDK

Integrate with OtplessBM SDK

`DeviceFingerprintMode` values

Fetch device intelligence

Pass additional context (optional)

`UpdateInfo` fields

Get the detailed report (server-side)

Sample response

Success

Error

Response fields

Error reference

Troubleshooting

​Prerequisites

​Installation

​Add permissions

​Initialize the SDK

​Integrate with OtplessBM SDK

​DeviceFingerprintMode values

​Fetch device intelligence

​Pass additional context (optional)

​UpdateInfo fields

​Get the detailed report (server-side)

​Sample response

​Success

​Error

​Response fields

​Error reference

​Troubleshooting

Prerequisites

Installation

Add permissions

Initialize the SDK

Integrate with OtplessBM SDK

`DeviceFingerprintMode` values

Fetch device intelligence

Pass additional context (optional)

`UpdateInfo` fields

Get the detailed report (server-side)

Sample response

Success

Error

Response fields

Error reference

Troubleshooting