iOS SDK

The iOS SDK mirrors the browser SDK: configure it on startup, call getSession() when the user performs a sensitive action, and POST the sealed token to your backend for verification.

New iOS integrations are temporarily paused while the SDK moves to Foil’s unified session transport. The iOS SDK remains supported, but the currently published release will receive transport.upgrade_required until that update ships.

import Foil

try FoilClient.shared.configure(
    FoilConfiguration(publishableKey: "pk_live_...")
)

// At action time (signup, login, checkout)
let handoff = try await FoilClient.shared.getSession()

Requirements

iOS 14+ for the public binary SwiftPM package
Swift 5.9+
Xcode 15+
A Foil publishable key created with the iOS client, starting with pk_live_ or pk_test_

Create a publishable key for iOS

In the Foil dashboard, open API Keys, choose New publishable key, and set Client to iOS. Foil admits native sessions only when the publishable key’s client matches the SDK’s platform. A key created with the Web or Android client is rejected, and the SDK reports config.invalid_publishable_key. In the other direction, the browser SDK doesn’t accept a key created with the iOS client.

Install

Add Foil with Swift Package Manager:

// Package.swift
dependencies: [
    .package(url: "https://github.com/abxy-labs/foil-ios", from: "1.2.2"),
],

Then add the Foil product to your app target. In Xcode, choose File > Add Package Dependencies…, enter https://github.com/abxy-labs/foil-ios, choose version 1.2.2 or newer, and add the Foil product to the target that configures the SDK.

Configure on startup

Configure once at app launch - typically from your App initializer - so signal collection is running by the time the first screen appears.

import SwiftUI
import Foil

@main
struct MyApp: App {
    init() {
        do {
            try FoilClient.shared.configure(
                FoilConfiguration(publishableKey: "pk_live_your_publishable_key")
            )
        } catch {
            // Reporting only - do not crash on Foil misconfiguration.
            print("Foil failed to configure:", error)
        }
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

`FoilConfiguration`

public struct FoilConfiguration: Sendable {
    public static let defaultAPIEndpoint: URL
    public let publishableKey: String
    public var enableBehavioralSignals: Bool
    public var enableHiddenWebView: Bool
    public var enableCloudIdentifier: Bool
    public var enableAutoAttachTouches: Bool
    public var apiEndpoint: URL
}

Field	Default	Description
`publishableKey`	-	Required. Must start with `pk_live_` or `pk_test_` and be created with the iOS client. Secret keys (`sk_*`) are rejected at configure-time.
`enableBehavioralSignals`	`true`	Zero-config native behavioral capture: app lifecycle, navigation, input, scroll, and motion. Touch-stroke observers are opt-in.
`enableHiddenWebView`	`true`	Enables the `attach(to:)` handoff so an in-app `WKWebView` shares this session.
`enableCloudIdentifier`	`false`	Opt-in iCloud KVS continuity hint. Requires the iCloud Key-Value Store entitlement on your app to survive reinstall.
`enableAutoAttachTouches`	`false`	Automatically attaches touch observation to app windows. Leave off if you call `observeTouches(on:contextId:)` manually.
`apiEndpoint`	production API	Advanced override for local development or private deployments.

Runtime integrity and anti-tamper collection is always enabled. It is part of the baseline SDK behavior, not an integration option.

Get a session at action time

Call getSession() from an async context right before the sensitive action - not on app launch.

struct CheckoutView: View {
    func submit() async {
        do {
            let handoff = try await FoilClient.shared.getSession()

            var request = URLRequest(url: URL(string: "https://api.example.com/checkout")!)
            request.httpMethod = "POST"
            request.setValue("application/json", forHTTPHeaderField: "Content-Type")
            request.httpBody = try JSONEncoder().encode(CheckoutRequest(
                items: cart,
                foil: .init(
                    sessionId: handoff.sessionId,
                    sealedToken: handoff.sealedToken
                )
            ))

            _ = try await URLSession.shared.data(for: request)
        } catch {
            // Decide how to treat a missing handoff - see Fallback policy below.
        }
    }
}

SessionHandoff is a small value type:

public struct SessionHandoff: Sendable, Equatable {
    public let sessionId: String
    public let sealedToken: String
}

sessionId is stable for the life of the client.
getSession() posts the native snapshot, performs a bounded best-effort behavioral flush, and returns the handoff your backend should verify.
The SDK never surfaces verdicts, scores, or visitor IDs to the device - verify on your server.

Your backend verifies a native handoff the same way it verifies a browser handoff. getSession() returns the same sessionId and sealedToken pair as the browser SDK, so you verify the sealedToken with your Foil server SDK and your secret key. See Server verification for the verification methods and examples in each server language.

Behavioral capture

When enableBehavioralSignals is true, the SDK starts zero-config UIKit capture automatically. It records the native equivalents of the browser’s behavioral events: app lifecycle, hashed screen navigation, viewport and scroll, form focus and input, selection and clipboard, and motion. No raw form text, raw placeholders, or raw field identifiers are sent. Field identity is hashed, and geometry is rounded to the field’s window coordinates so the dashboard can show timing and replay context without collecting user-entered values. Touch-stroke dynamics are still opt-in per screen for higher-fidelity gesture data. Call observeTouches(on:) once the view is mounted.

class CheckoutViewController: UIViewController {
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        FoilClient.shared.observeTouches(on: view, contextId: "checkout")
    }
}

The observer attaches a non-consuming gesture recognizer, so your existing gestures keep working unchanged. In SwiftUI, reach for a UIViewRepresentable wrapper to expose the underlying UIView.

WebView correlation

If your app hosts Foil-protected web content in a WKWebView, attach it so the web SDK reuses the native session.

import WebKit

let webView = WKWebView(frame: .zero)
FoilClient.shared.attach(to: webView)
webView.load(URLRequest(url: URL(string: "https://your-app.example.com/signup")!))

The native bridge exposes the session handoff as window.__FOIL_NATIVE__, which the browser SDK picks up when loaded inside the WebView.

Native identity and attestation

Native visitor continuity is resolved server-side from the SDK’s encrypted observations. install_id tracks the app install, device_id tracks the device continuity layer, and native visitor_id represents the same device within your organization. None of those identifiers are exposed to the app. Apple App Attest is optional and positive-only by default. When App Attest is supported, Foil can use SDK-managed App Attest keys to strengthen native identity. When it is unsupported, unavailable, unconfigured, or fails verification, Foil falls back to the other native continuity signals unless your organization explicitly enables strict attestation.

To verify App Attest in production, add your iOS app identity on the Native Attestation card of the dashboard’s Settings page. Baseline native continuity still works without this setup, but App Attest doesn’t upgrade identity confidence until the app identity is configured.

Add your app identity

Only organization owners and admins can change attestation settings. On the Native Attestation card, under Add app identity:

Set Platform to iOS.
Enter your Apple App ID, which is your Apple Team ID and your bundle ID joined by a period, such as TEAMID.com.example.app.
Select Add identity.

The Attestation policy setting on the same card controls how Foil treats attestation:

Policy	Behavior
Positive only (default)	Verified App Attest can strengthen identity. Missing or unsupported attestation doesn’t break continuity.
Strict	Foil requires verified attestation from an app identity on the App identity allowlist. Add every app identity you ship before you switch to this policy, then select Save policy.

Diagnostics

dispatchHealth() returns per-channel counters of successful and failed batch posts since the last configure(_:). Use it to confirm signals are reaching the server when you don’t have server-side visibility - for example, to spot a TLS-pinning, proxy, or quota issue from the client.

let health = await FoilClient.shared.dispatchHealth()
for (channel, stats) in health.channels {
    print(channel,
          "ok:", stats.consecutiveSuccesses,
          "fail:", stats.consecutiveFailures)
}

consecutiveFailures rising without a matching rise in consecutiveSuccesses typically means a sustained network outage or a server-side rejection that retries can’t recover from. Counters reset on configure(_:), destroy(), or resetLocalState().

API reference

Method	Description
`FoilClient.shared.configure(_:)`	Validates the publishable key and starts the runtime. Throws `FoilError` on invalid input.
`FoilClient.shared.getSession() async throws -> SessionHandoff`	Posts the snapshot, performs a bounded best-effort behavioral flush, and returns a sealed handoff.
`FoilClient.shared.waitForFingerprint() async throws`	Resolves when the visitor fingerprint is ready. Optional - `getSession()` works without it.
`FoilClient.shared.pauseCollection() async`	Pauses active collection without ending the session. Later `getSession()` calls stay valid but don’t include events recorded while paused. Call it after a protected flow completes.
`FoilClient.shared.stop() async`	Alias for `pauseCollection()`.
`FoilClient.shared.resumeCollection()`	Resumes collection after `pauseCollection()` or `stop()` without creating a new session.
`FoilClient.shared.observeTouches(on:contextId:)`	Attaches a non-consuming gesture recognizer to the view. Call once per screen.
`FoilClient.shared.attach(to:)`	Shares the current session with a hosted `WKWebView`.
`FoilClient.shared.dispatchHealth() async -> DispatchHealthSnapshot`	Per-channel batch-post counters since the last `configure(_:)`. Useful for confirming telemetry is reaching the server.
`FoilClient.shared.resetLocalState()`	Stops the runtime and clears the persisted session and outbox state. Long-lived install/device anchors are preserved.
`FoilClient.shared.destroy()`	Stops timers and releases resources. Rarely needed outside tests.

Error handling

FoilError is a Sendable struct carrying a stable code, a human-readable message, an optional underlying error, and a retryable flag.

public struct FoilError: Error, Sendable {
    public enum Code: String, Sendable {
        case invalidPublishableKey = "config.invalid_publishable_key"
        case notConfigured         = "client.not_configured"
        case sessionCreateFailed   = "session.create_failed"
        case batchPostFailed       = "transport.batch_post_failed"
        case handshakeExpired      = "session.handshake_expired"
        case sessionInvalidOrExpired = "session.invalid_or_expired"
        case rateLimited           = "transport.rate_limited"
        case serverUpgradeRequired = "transport.upgrade_required"
        case network               = "transport.network"
        case cryptoFailure         = "crypto.failure"
        case internalError         = "internal"
    }

    public let code: Code
    public let message: String
    public let underlying: Error?
    public let retryable: Bool
}

Code	Retryable	When it happens
`config.invalid_publishable_key`	no	`publishableKey` is missing, uses the `sk_` secret prefix, or doesn’t match `pk_live_` / `pk_test_`. The SDK also returns this code when the API rejects the key (HTTP 401 or 403), for example because the key was created with the Web* or Android client instead of iOS.
`client.not_configured`	no	A client method was called before `configure(_:)`.
`session.create_failed`	varies	Session handshake with the Foil API failed.
`session.handshake_expired`	no	The server expired the session. Call `configure(_:)` again to mint a new one.
`session.invalid_or_expired`	no	The active session is invalid or expired.
`transport.batch_post_failed`	varies	A signal batch upload failed.
`transport.rate_limited`	yes	HTTP 429 from the API. Back off and retry.
`transport.upgrade_required`	no	HTTP 410/426. The SDK version is too old - upgrade the app.
`transport.network`	yes	DNS, TLS, or connectivity failure.
`crypto.failure`	no	A crypto primitive failed. Usually a platform issue worth reporting.
`internal`	no	Unexpected state. File a support ticket with the message and underlying error.

The code values are stable. Category prefixes (config.*, transport.*) are safe to branch on with a wildcard - new codes within a category keep the same retry semantics.

Fallback policy

If Foil fails, log the error and continue without a handoff, then decide on your server how to treat a request that has no Foil signal. For low-risk actions you can fail open. For sensitive actions such as signup, payment, or account recovery, fail closed or step up verification.

func foilHandoff() async -> SessionHandoff? {
    do {
        return try await FoilClient.shared.getSession()
    } catch let err as FoilError where err.retryable {
        return try? await FoilClient.shared.getSession()
    } catch {
        reportError(error)
        return nil
    }
}

See Signup & account creation for an example of failing closed when verification fails, and Going to production for the rollout sequence.

Best practices

Configure once at launch so signals are collecting before any screen opens.
Call getSession() late - right before the sensitive action, from an async context.
Set a fallback policy per action - when the SDK can’t produce a handoff, fail open on low-risk actions and fail closed on sensitive ones.
Reuse the shared client - FoilClient.shared is a process-wide singleton.

What’s next

Server verification

Verify the sealed token on your backend

Browser SDK

Equivalent guide for the web surface

Android SDK

Native Android integration

Going to production

Rollout checklist and monitoring

Overview

Get started

Integrate

Use cases

Learn

Resources

Requirements

Create a publishable key for iOS

Install

Configure on startup

`FoilConfiguration`

Get a session at action time

Behavioral capture

WebView correlation

Native identity and attestation

Add your app identity

Diagnostics

API reference

Error handling

Fallback policy

Best practices

What’s next

Server verification

Browser SDK

Android SDK

Going to production

​Requirements

​Create a publishable key for iOS

​Install

​Configure on startup

​FoilConfiguration

​Get a session at action time

​Behavioral capture

​WebView correlation

​Native identity and attestation

​Add your app identity

​Diagnostics

​API reference

​Error handling

​Fallback policy

​Best practices

​What’s next

Server verification

Browser SDK

Android SDK

Going to production

Requirements

Create a publishable key for iOS

Install

Configure on startup

`FoilConfiguration`

Get a session at action time

Behavioral capture

WebView correlation

Native identity and attestation

Add your app identity

Diagnostics

API reference

Error handling

Fallback policy

Best practices

What’s next