# OZ Liveness SDK

OZ Liveness SDK is an iOS framework developed by OZ Forensics for implementing liveness detection and face biometry analysis in mobile applications. The SDK enables developers to capture video, verify that a real person is present (anti-spoofing), and perform facial recognition comparisons against reference images. It supports both server-side analysis via the OZ API and on-device processing for offline scenarios.

The SDK integrates with iOS applications through CocoaPods and requires a license file obtained from OZ Forensics. It provides a complete workflow including video capture controllers, gesture-based liveness challenges (smile, blink, head movements), and analysis APIs that return verification results with confidence scores. The framework supports multiple localizations including English, Spanish, Russian, Turkish, Kazakh, Kyrgyz, Armenian, and Portuguese.

## SDK Installation

Install OZ Liveness SDK using CocoaPods dependency manager. The standard installation includes full functionality with on-device analysis, while the Core subspec provides server-only analysis without local ML models.

```ruby
# Podfile - Install latest version with full functionality
pod 'OZLivenessSDK'

# OR install a specific version
pod 'OZLivenessSDK', '8.21.0'

# OR install Core version without on-device analysis (smaller package size)
pod 'OZLivenessSDK/Core'
```

## License Initialization

Initialize the SDK with a license file to enable functionality. The license is tied to your application's bundle ID. You can either place a file named `forensics.license` in your project bundle for automatic detection, or specify the license path programmatically during initialization.

```swift
import OZLivenessSDK

// Option 1: Initialize with license file name (file must be in app bundle)
OZSDK(licenseSources: [.licenseFileName("forensics.license")]) { licenseData, error in
    if let error = error {
        print("License error: \(error.localizedDescription)")
        return
    }
    if let data = licenseData {
        print("License valid until: \(data.expirationDate)")
        print("Licensed features: \(data.features)")
    }
}

// Option 2: Initialize with full file path
OZSDK(licenseSources: [.licenseFilePath("/path/to/your/license.file")]) { licenseData, error in
    if let error = error {
        print("License error: \(error.localizedDescription)")
        return
    }
}

// Check license data manually after initialization
if let currentLicense = OZSDK.licenseData {
    print("Current license: \(currentLicense)")
}
```

## API Connection with Service Token

Connect the SDK to the OZ Forensics API using a service token. This authentication method is recommended for server-to-server communication where the token is securely managed.

```swift
import OZLivenessSDK

let host = "https://api.ozforensics.com"
let token = "your-service-token"

let connection = Connection.fromServiceToken(host: host, token: token)
OZSDK.setApiConnection(connection) { authToken, error in
    if let error = error {
        print("Connection failed: \(error.localizedDescription)")
        return
    }
    if let authToken = authToken {
        print("Connected successfully with token: \(authToken)")
        // SDK is now ready to upload media and perform analysis
    }
}
```

## API Connection with Credentials

Connect to the OZ Forensics API using login credentials provided by your account manager. This method authenticates with username and password to obtain an access token.

```swift
import OZLivenessSDK

let host = "https://api.ozforensics.com"
let login = "your-username"
let password = "your-password"

let connection = Connection.fromCredentials(host: host, login: login, password: password)
OZSDK.setApiConnection(connection) { authToken, error in
    if let error = error {
        print("Authentication failed: \(error.localizedDescription)")
        return
    }
    if let authToken = authToken {
        print("Authenticated successfully")
        // Proceed with video capture and analysis
    }
}
```

## Analysis Request Builder

Use the AnalysisRequest builder pattern to create and execute liveness and biometry analysis. This API allows you to add media files, specify analysis types, attach metadata, and receive results through completion handlers.

```swift
import OZLivenessSDK

// Create analysis request with optional folder ID for grouping
let request = AnalysisRequestBuilder(nil)

// Add captured media (video or image) to the request
let videoMedia = OZMedia(videoURL: capturedVideoURL)
request.addMedia(videoMedia)

// Add reference photo for biometry comparison
let photoMedia = OZMedia(imageURL: referencePhotoURL)
request.addMedia(photoMedia)

// Specify analysis types to perform
request.addAnalysis(.liveness)        // Check if person is live (anti-spoofing)
request.addAnalysis(.biometry)        // Compare faces between media

// Add custom metadata to the analysis folder
request.addFolderMeta([
    "userId": "user-12345",
    "sessionId": "session-abc",
    "timestamp": Date().timeIntervalSince1970
])

// Execute the analysis with progress tracking
request.run(
    scenarioProgressHandler: { state in
        // Track scenario execution state
        print("Scenario state: \(state)")
    },
    uploadProgressHandler: { status in
        // Track upload progress
        switch status {
        case .uploading(let progress):
            print("Upload progress: \(progress * 100)%")
        case .completed:
            print("Upload completed")
        case .failed(let error):
            print("Upload failed: \(error)")
        }
    },
    completionHandler: { result, error in
        if let error = error {
            print("Analysis failed: \(error.localizedDescription)")
            return
        }

        guard let analysisResult = result else { return }

        // Process liveness result
        if let livenessResolution = analysisResult.livenessResolution {
            print("Liveness passed: \(livenessResolution.passed)")
            print("Liveness confidence: \(livenessResolution.confidence)")
        }

        // Process biometry result
        if let biometryResolution = analysisResult.biometryResolution {
            print("Faces match: \(biometryResolution.matched)")
            print("Similarity score: \(biometryResolution.similarity)")
        }
    }
)
```

## On-Device Liveness Analysis

Perform liveness detection locally on the device without network connectivity. This method uses TensorFlow Lite models bundled with the SDK for real-time analysis.

```swift
import OZLivenessSDK

// Captured video from the liveness check UI
let capturedVideo = OZMedia(videoURL: localVideoURL)

// Run on-device liveness analysis (no network required)
OZSDK.runOnDeviceLivenessAnalysis(media: capturedVideo) { result, error in
    if let error = error {
        print("On-device analysis failed: \(error.localizedDescription)")
        return
    }

    guard let livenessResult = result else { return }

    print("Is live person: \(livenessResult.isLive)")
    print("Confidence score: \(livenessResult.confidence)")
    print("Spoof type detected: \(livenessResult.spoofType ?? "none")")

    if livenessResult.isLive && livenessResult.confidence > 0.9 {
        print("High confidence liveness verified")
        // Proceed with user verification flow
    }
}
```

## On-Device Biometry Analysis

Compare two face images locally on the device to determine if they belong to the same person. Useful for offline face matching scenarios.

```swift
import OZLivenessSDK

// Reference photo (e.g., from ID document)
let referencePhoto = OZMedia(imageURL: idPhotoURL)

// Live capture photo
let livePhoto = OZMedia(imageURL: selfieURL)

// Run on-device biometry comparison
OZSDK.runOnDeviceBiometryAnalysis(
    referenceMedia: referencePhoto,
    targetMedia: livePhoto
) { result, error in
    if let error = error {
        print("Biometry analysis failed: \(error.localizedDescription)")
        return
    }

    guard let biometryResult = result else { return }

    print("Faces match: \(biometryResult.matched)")
    print("Similarity score: \(biometryResult.similarity)")  // 0.0 to 1.0

    if biometryResult.matched && biometryResult.similarity > 0.85 {
        print("Identity verified - faces match with high confidence")
    } else {
        print("Identity verification failed - faces do not match")
    }
}
```

## Upload and Analyze Media

Upload captured media to the OZ API server and immediately start analysis in a single operation. This combines upload and analysis initiation for streamlined integration.

```swift
import OZLivenessSDK

let capturedMedia = [
    OZMedia(videoURL: livenessVideoURL),
    OZMedia(imageURL: documentPhotoURL)
]

let analysisTypes: [AnalysisType] = [.liveness, .biometry, .documentAnalysis]

OZSDK.uploadAndAnalyse(
    media: capturedMedia,
    analyses: analysisTypes
) { verificationResult, error in
    if let error = error {
        print("Upload and analysis failed: \(error.localizedDescription)")
        return
    }

    guard let result = verificationResult else { return }

    // Access best quality captures
    if let bestShotURL = result.bestShotURL {
        print("Best shot image: \(bestShotURL)")
    }
    if let preferredVideoURL = result.preferredMediaURL {
        print("Best quality video: \(preferredVideoURL)")
    }

    // Check verification status
    print("Verification passed: \(result.passed)")
    print("Folder ID: \(result.folderId)")
}
```

## Force License Replacement

Replace an existing active license with a new one. By default, the SDK won't replace a valid license during initialization. Use this method to force update the license.

```swift
import OZLivenessSDK

// Force replace current license with a new one
OZSDK.setLicense(source: .licenseFileName("new-forensics.license")) { licenseData, error in
    if let error = error {
        print("License replacement failed: \(error.localizedDescription)")
        return
    }

    if let data = licenseData {
        print("New license activated")
        print("Expiration: \(data.expirationDate)")
    }
}
```

---

OZ Liveness SDK is primarily used for identity verification workflows in banking, fintech, and security applications. Common use cases include customer onboarding (KYC), secure authentication, fraud prevention, and access control systems. The SDK's combination of liveness detection and face matching enables applications to verify that a real person is present and matches their claimed identity, protecting against photo attacks, video replays, and mask-based spoofing attempts.

Integration typically follows a three-step pattern: (1) initialize the SDK with license and API credentials, (2) present the video capture UI to guide users through liveness gestures, and (3) submit captured media for analysis and handle the verification results. For offline scenarios or privacy-sensitive applications, the on-device analysis methods provide local processing without transmitting biometric data to external servers. The SDK supports customization of the capture UI appearance and can be integrated with existing authentication flows through its completion handler-based API design.