Overview

iOS Support Status

iOS client integration is planned but not the primary path in current repo state. This section provides guidance for maintaining parity with Android when implementing iOS support.

Parity Goals with Android

When adding iOS, maintain these contract semantics:

Event Naming and Payloads

• Same event names: identity, screen_schema, component_input, validation_failed, error_reported
• Same field semantics for context, masking, and validation
• Same trace header propagation (traceparent, X-Request-ID)

Backend Contract

• Same endpoints: /v1/events, /v1/assistant/*, /v1/sdk/config
• Same request/response shapes (see API_CONTRACTS.md)
• Same header requirements: X-API-Key, X-KYCIS-SDK-Version, X-Client-ID

Voice Integration

• Same LiveKit room join flow
• Same JWT token handling
• Same session start/stop lifecycle

Recommended iOS Structure

Mirror the Android SDK organization:

KYCISiOSSDK/
├── AI.swift                    # Public facade
├── Runtime/
│   ├── RuntimeContext.swift
│   ├── RuntimePolicy.swift
│   └── SdkRuntime.swift
├── Network/
│   ├── BackendClient.swift
│   └── HttpBackendClient.swift
├── Lifecycle/
│   └── LifecycleTracker.swift
└── Voice/
    └── VoiceRoomConnector.swift

Swift API Sketch

// Initialization
AI.init(
    apiKey: "your-api-key",
    userId: "user-123",
    policy: RuntimePolicy(
        backendBaseUrl: "https://kycis.zynnex.in/v1",
        clientId: "your-client-id",
        mappingVersion: "v1"
    )
)

// Lifecycle attachment
AI.attach(UIApplication.shared)

// Identity
AI.setUser(id: "user-123", phone: "9876543210", phoneMasked: true)

// Step context
AI.setKycStep("phone_entry")

// Validation failure
AI.trackValidationFailure(
    failureReasonCode: "pan_invalid",
    componentId: "pan_field",
    componentType: "text_input"
)

// Voice session
AI.setVoiceSessionListener { result in
    if result.isValid {
        // Connect to LiveKit
    }
}
AI.startAssistant()

Platform-Specific Considerations

Permissions

• NSMicrophoneUsageDescription in Info.plist
• Request microphone permission before voice session

Lifecycle

• Use UIApplicationDelegate or SceneDelegate for lifecycle observation
• Track view controller transitions for screen context

Networking

• Use URLSession with proper timeout configuration
• Handle background/foreground transitions gracefully

Backend Requirements

No backend changes needed for iOS — same endpoints, same contracts. Ensure:

• CORS allows iOS app origins if using web views
• SSL certificates valid for iOS trust store

Integration Verification

Same verification steps as Android:

1. Events appear in /api/activity
2. Trigger evaluations return expected results
3. Voice sessions start/stop correctly
4. Context builds correctly for voice agent