Integração iOS

🍎 Integração iOS

O SDK é Kotlin Multiplatform, então o mesmo fluxo de commonMain (fetchConfig → buildSolution → login) é exposto ao iOS por meio de um framework Kotlin/Native gerado, que você importa a partir do Swift.

⚠️ Estado atual — estruturado, ainda não validado. O target iOS compila e a API pública é chamável a partir do Swift, mas as peças de plataforma são stubs: a identidade recai no tier uuid e cada coletor reporta como indisponível. O ciclo de login funciona ponta a ponta; os sinais do dispositivo apenas ficam vazios até que os coletores nativos e a identidade via Secure Enclave sejam implementados. Use esta página para ligar o app agora e entender o contrato que um port completo cumprirá.

---

1. Gere / importe o framework

Produza o framework Kotlin/Native a partir do módulo do SDK e ligue‑o no Xcode (diretamente, ou via CocoaPods / Swift Package Manager quando configurado):

# Simulador (Apple Silicon)
./gradlew :sdk:linkDebugFrameworkIosSimulatorArm64
# Dispositivo
./gradlew :sdk:linkReleaseFrameworkIosArm64

O framework expõe a API io.guardiankey.gkas ao Swift. Funções suspend do Kotlin são convertidas para funções async do Swift (ou completion handlers).

---

2. Crie a instância do SDK

No iOS o PlatformContext é vazio (não é necessário um Context do Android). Construa o SDK e chame os mesmos três passos.

import shared   // o nome do framework Kotlin/Native

let config = GkasSdkConfig(
    backendBaseUrl: "https://seu-backend.exemplo.com/api",
    httpTimeoutMs: 8000,
    debug: false
)

let gkas = GuardianKeyGkas.companion.create(
    config: config,
    platform: PlatformContext()
)

---

3. Conduza o login

func login(username: String, password: String) async {
    do {
        // 1) GET /config
        let config = try await gkas.fetchConfig()

        // 2) coleta sinais + resolve/assina identidade → gkas_solution (Base64)
        let solution = try await gkas.buildSolution(config: config, fieldValue: username)

        // 3) POST /login
        let request = LoginRequest(
            username: username,
            password: password,
            gkasSolution: solution,
            config: config
        )
        let result = try await gkas.login(request: request)

        switch result {
        case let allowed as LoginResultAllowed:
            goToHome()
        case let blocked as LoginResultBlocked:
            showBlocked(blocked.reason)        // permanece no login
        case let error as LoginResultError:
            showError(error.message)
        default:
            break
        }
    } catch {
        showError("Falha de comunicação: \(error)")
    }
}

O contrato é idêntico ao do Android, e o backend retorna uma decisão normalizada ALLOW / BLOCK.

---

4. O que um port iOS completo acrescenta

Os stubs estruturados em iosMain marcam onde entra o trabalho nativo. Uma implementação iOS completa fornece duas coisas:

• Identidade nativa do dispositivo — sustentando os tiers software e biometric com o hardware seguro da plataforma (Secure Enclave) e LocalAuthentication para o prompt biométrico, no lugar do atual fallback uuid.
• Coletores de sinais nativos — os equivalentes iOS dos sinais de dispositivo/comportamento, para que a mesma informação que o build Android contribui também seja reunida no iOS.

Até que isso seja implementado, a identidade recai no tier uuid e os sinais reportam como indisponíveis; o ciclo de login continua funcionando.

Como no Android, cada coletor deve permanecer best‑effort e nunca lançar — quando uma permissão ou capacidade estiver ausente, ele reporta indisponível e o login prossegue. Um port completo também declara as usage descriptions correspondentes no Info.plist e os entitlements; sem eles os coletores correspondentes permanecem indisponíveis por design.

---

Veja a referência de API para a API pública compartilhada e o contrato do backend.