Mobile apps

<key>NSCameraUsageDescription</key>
<string>We use the camera to confirm your identity with a short face check and a photo of your ID.</string>

dependencies:
  speedmap_capture: ^0.1.0

import AVFoundation
import UIKit
import WebKit

/// Presents the Speedmap capture page for one capture session.
final class SpeedmapCaptureViewController: UIViewController, WKNavigationDelegate, WKUIDelegate, WKScriptMessageHandler {
    var onComplete: ((_ sessionId: String?) -> Void)?
    var onCancel: (() -> Void)?
    var onError: ((_ code: String, _ recoverable: Bool) -> Void)?

    private let captureURL: URL
    private var webView: WKWebView!

    /// captureURL: the url your server got from POST /v1/capture-sessions.
    init(captureURL: URL) {
        var parts = URLComponents(url: captureURL, resolvingAgainstBaseURL: false)!
        parts.queryItems = (parts.queryItems ?? []) + [URLQueryItem(name: "embed", value: "1")]
        self.captureURL = parts.url!
        super.init(nibName: nil, bundle: nil)
    }
    required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }

    override func loadView() {
        let config = WKWebViewConfiguration()
        config.allowsInlineMediaPlayback = true                 // camera preview inside the page
        config.mediaTypesRequiringUserActionForPlayback = []
        config.userContentController.add(WeakMessageHandler(self), name: "speedmap")

        webView = WKWebView(frame: .zero, configuration: config)
        webView.navigationDelegate = self
        webView.uiDelegate = self
        webView.scrollView.contentInsetAdjustmentBehavior = .never // the page applies safe-area insets itself
        view = webView
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        // Ask for the camera first so the system prompt appears over your app, not mid-flow.
        AVCaptureDevice.requestAccess(for: .video) { _ in
            DispatchQueue.main.async { self.webView.load(URLRequest(url: self.captureURL)) }
        }
    }

    deinit { webView?.configuration.userContentController.removeScriptMessageHandler(forName: "speedmap") }

    // iOS 15+: give the capture page the camera without a second, web-style prompt.
    @available(iOS 15.0, *)
    func webView(_ webView: WKWebView, requestMediaCapturePermissionFor origin: WKSecurityOrigin,
                 initiatedByFrame frame: WKFrameInfo, type: WKMediaCaptureType,
                 decisionHandler: @escaping (WKPermissionDecision) -> Void) {
        decisionHandler(origin.host == captureURL.host && type == .camera ? .grant : .deny)
    }

    // Stay on the capture origin; anything else (for example your success_url) is not followed.
    func webView(_ webView: WKWebView, decidePolicyFor action: WKNavigationAction,
                 decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
        let url = action.request.url
        let allowed = url?.host == captureURL.host || url?.scheme == "about" || url?.scheme == "blob"
        decisionHandler(allowed ? .allow : .cancel)
    }

    func userContentController(_ controller: WKUserContentController, didReceive message: WKScriptMessage) {
        guard message.frameInfo.isMainFrame,
              message.frameInfo.securityOrigin.host == captureURL.host,
              let body = message.body as? String,
              let msg = try? JSONDecoder().decode(SpeedmapMessage.self, from: Data(body.utf8)),
              msg.source == "speedmap" else { return }
        switch msg.type {
        case "complete": onComplete?(msg.session_id)
        case "cancel": onCancel?()
        case "error": onError?(msg.code ?? "internal", msg.recoverable ?? false)
        default: break // "ready" and "event": progress, e.g. msg.event == "step.complete"
        }
    }
}

struct SpeedmapMessage: Decodable {
    let source: String
    let version: Int
    let type: String          // ready | event | complete | error | cancel
    let flow: String?
    let session_id: String?
    let status: String?
    let steps: [String]?
    let event: String?
    let step: String?
    let reference_id: String?
    let code: String?
    let recoverable: Bool?
}

/// WKUserContentController retains its handlers; this breaks the cycle.
private final class WeakMessageHandler: NSObject, WKScriptMessageHandler {
    weak var target: WKScriptMessageHandler?
    init(_ target: WKScriptMessageHandler) { self.target = target }
    func userContentController(_ c: WKUserContentController, didReceive m: WKScriptMessage) {
        target?.userContentController(c, didReceive: m)
    }
}

import android.Manifest
import android.annotation.SuppressLint
import android.content.Intent
import android.content.pm.PackageManager
import android.net.Uri
import android.os.Bundle
import android.webkit.*
import androidx.activity.addCallback
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.ContextCompat
import androidx.core.view.ViewCompat
import androidx.core.view.WindowInsetsCompat
import org.json.JSONObject

/** Shows the Speedmap capture page for one capture session. Start with EXTRA_URL = the session url. */
class SpeedmapCaptureActivity : AppCompatActivity() {
    companion object {
        const val EXTRA_URL = "speedmap_url"
        const val RESULT_SESSION_ID = "session_id"
    }

    private lateinit var webView: WebView
    private lateinit var captureUrl: Uri
    private var pendingRequest: PermissionRequest? = null

    private val cameraPermission = registerForActivityResult(ActivityResultContracts.RequestPermission()) { granted ->
        pendingRequest?.let { if (granted) it.grant(arrayOf(PermissionRequest.RESOURCE_VIDEO_CAPTURE)) else it.deny() }
        pendingRequest = null
    }

    @SuppressLint("SetJavaScriptEnabled")
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        captureUrl = Uri.parse(intent.getStringExtra(EXTRA_URL)).buildUpon()
            .appendQueryParameter("embed", "1").build()

        webView = WebView(this)
        setContentView(webView)
        // Edge-to-edge (Android 15+): keep the page clear of the status and navigation bars.
        ViewCompat.setOnApplyWindowInsetsListener(webView) { v, insets ->
            val bars = insets.getInsets(WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout())
            v.setPadding(bars.left, bars.top, bars.right, bars.bottom)
            WindowInsetsCompat.CONSUMED
        }

        webView.settings.apply {
            javaScriptEnabled = true
            domStorageEnabled = true
            mediaPlaybackRequiresUserGesture = false   // camera preview starts without a tap
            allowFileAccess = false
            allowContentAccess = false
        }
        webView.addJavascriptInterface(Bridge(), "SpeedmapAndroid")

        webView.webViewClient = object : WebViewClient() {
            // Stay on the capture origin; anything else (for example your success_url) is not followed.
            override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest) =
                request.url.host != captureUrl.host
        }
        webView.webChromeClient = object : WebChromeClient() {
            // getUserMedia from the page: camera only, capture origin only.
            override fun onPermissionRequest(request: PermissionRequest) = runOnUiThread {
                val camera = PermissionRequest.RESOURCE_VIDEO_CAPTURE
                if (request.origin.host != captureUrl.host || !request.resources.contains(camera)) {
                    request.deny()
                } else if (ContextCompat.checkSelfPermission(this@SpeedmapCaptureActivity, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED) {
                    request.grant(arrayOf(camera))
                } else {
                    pendingRequest = request
                    cameraPermission.launch(Manifest.permission.CAMERA)
                }
            }
        }

        onBackPressedDispatcher.addCallback(this) { setResult(RESULT_CANCELED); finish() }
        webView.loadUrl(captureUrl.toString())
    }

    override fun onDestroy() {
        webView.destroy()
        super.onDestroy()
    }

    private inner class Bridge {
        /** Called by the page on a background thread with one JSON message. */
        @JavascriptInterface
        fun postMessage(json: String) = runOnUiThread {
            // Only trust messages while the capture origin is loaded.
            if (Uri.parse(webView.url ?: "").host != captureUrl.host) return@runOnUiThread
            val msg = runCatching { JSONObject(json) }.getOrNull() ?: return@runOnUiThread
            if (msg.optString("source") != "speedmap") return@runOnUiThread
            when (msg.optString("type")) {
                "complete" -> {
                    setResult(RESULT_OK, Intent().putExtra(RESULT_SESSION_ID, msg.optString("session_id")))
                    finish()
                }
                "cancel" -> { setResult(RESULT_CANCELED); finish() }
                "error" -> if (!msg.optBoolean("recoverable")) { setResult(RESULT_CANCELED); finish() }
                else -> Unit // "ready" and "event": progress
            }
        }
    }
}

{
  "source": "speedmap",
  "version": 1,
  "type": "ready",
  "flow": "capture",
  "session_id": "cap_9d9d78ebe9f53966",
  "status": "created",
  "steps": [
    "liveness",
    "document"
  ]
}