# iOS Quick Start

From zero to a `YES` verdict on an iOS device in ten minutes.

:::note

Work through [Prerequisites](/docs/getting-started/prerequisites/) first. You will need a license key and the two `Info.plist` keys.

:::

---

## 1. Add the SDK

### Swift Package Manager (recommended)

In Xcode: **File -> Add Packages...** and enter:

```
https://github.com/octetproof/octet-sdk-ios
```

Pin to a version rather than tracking `main`. Or in `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/octetproof/octet-sdk-ios", exact: "1.2.1")
]
```

Pin 1.2.1 or later. Versions 1.0.0, 1.1.0, and 1.2.0 are deprecated for security reasons, and their release artifacts have been removed from GitHub, so a build pinned to one of them no longer resolves.

Then import:

```swift
import OctetSDK
```

### Carthage

Carthage does not propagate SwiftPM transitive dependencies. Add **two** lines to your `Cartfile`:

```
binary "https://raw.githubusercontent.com/octetproof/octet-sdk-ios/main/OctetSDK.json" >= 1.2.1
github "apple/swift-protobuf" ~> 1.28
```

The module name is `OctetSDK`.

### Verify the download (optional)

Each release publishes a SHA-256 checksum, SLSA build provenance, an SBOM (software bill of materials), and a keyless cosign signature for `OctetSDK.xcframework`. To check them in a release pipeline, follow the "Verifying the download" section of [`INTEGRATION.md`](https://github.com/octetproof/octet-sdk-ios/blob/main/INTEGRATION.md). A build runs without this step.

---

## 2. Add `Info.plist` keys

```xml
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app uses your location to verify and prove your location
to services that request it.</string>

<key>NSMotionUsageDescription</key>
<string>This app uses motion data to detect when you're stationary or
moving, which improves the confidence of location proofs.</string>
```

Without these, the app crashes on first launch.

The xcframework also bundles a privacy manifest (`PrivacyInfo.xcprivacy`) declaring the data types it handles (location, device identifier, aggregate usage counters) and its required-reason API use. Xcode folds this into your app's privacy report at build time, so you do not re-declare the SDK's data use.

---

## 3. Request location permission

The SDK refuses to start until the user grants location authorization. Request it before calling `Octet.start(...)`:

```swift
import CoreLocation

let locationManager = CLLocationManager()
locationManager.requestWhenInUseAuthorization()
```

Wait for the authorization status callback (`locationManagerDidChangeAuthorization`) before continuing.

---

## 4. Start the SDK

:::tip[Don't have a key yet?]
`licenseKey` is a placeholder. Get a free key (free for up to 1,000 proofs a month, no credit card) at **[sdk.octetproof.com/signup](https://sdk.octetproof.com/signup)**, then paste it in.
:::

```swift
import OctetSDK

let config = OctetConfig(licenseKey: "octet_live_v4.public....")
let sdk = try await Octet.start(config: config)
```

`Octet.start(...)` is `async throws`. On first launch the SDK verifies the license key locally, exchanges it for an activation token via `api.octetproof.com/v1/activate`, caches the token in Keychain, and brings up the proof pipeline. On subsequent launches the cached token is reused.

Any license problem throws a typed `LicenseError`. See [License Types](/docs/api-reference/license-types/) for the case list.

---

## 5. Ask your first question

```swift
let verdict = await sdk.loc.isWithin(
    region: .country(isoCode: "US"),
    atTime: Date()
)

switch verdict.result {
case .yes:
    print("YES, proof attached: \(verdict.proof != nil)")
case .no:
    print("NO, provable negative")
case .indeterminate:
    print("INDETERMINATE, reason: \(verdict.reason)")
}
```

The predicate returns an [`OctetVerdict`](/docs/api-reference/octet-verdict/). Never treat `INDETERMINATE` as `NO`.

---

## 6. What to expect

- **On a real device, outdoors**, with cellular and GPS available, `isWithin(.country(isoCode: ...))` typically returns `YES` with an attached proof.
- **On the iOS Simulator** the verdict will always be `INDETERMINATE / NO_FIX` with the message `running on simulator -- location proofs are unavailable in this environment`. This is by design. The simulator has no GNSS or motion stack, and the spoof-detection pipeline blocks proof generation. **Run on hardware** to see the full flow.
- **On a real device, indoors**, the first proof may take longer or come back at `MEDIUM` confidence. See [Concepts: Verdicts](/docs/concepts/verdicts/) for how confidence relates to the verdict.

---

## 7. From here

- The [OctetSample sample app](/docs/samples/ios-toy-app/) is a single-button SwiftUI app that exercises this whole flow.
- [Concepts: Proof of Location](/docs/concepts/proof-of-location/) explains what a verdict proves.
- [Session-binding](/docs/concepts/session-binding/) ties a proof to a specific login, so your verifier can confirm the proof was made for that login.
- [Verifying Proofs](/docs/concepts/verifying-proofs/) and the [Verifier Quick Start](/docs/getting-started/verifier-quickstart/) show how anyone can independently check the proofs your app produces.
- [What's new in 1.2](/docs/whats-new/) lists the API added since 1.1.
- [API Reference Overview](/docs/api-reference/overview/) maps the public surface.