This quickstart adds Trace to a native iOS app with the TraceDevice Swift package. You allow your app on a public key, identify the device before a sensitive action, and send the eventId to your backend for verification.
Partly verified
The core (payload, hashes and the identify call) passes its tests in CI on macOS: payload and hash parity with the TypeScript SDK, and the client against a stubbed network. The UIKit code that reads the device and stores the token in the Keychain only compiles for iOS, so CI does not build it and it is untested on a device. Try it in your app first.
Before you start
You need a running Trace server and a public key (pk_...). The quick start guide covers both. The SDK asks for no permission.
- 1
Install the SDK
swift// Package.swift, or Xcode: File > Add Package Dependencies. Until the repository is public, use a local path. .package(path: "../trace/sdks/swift") - 2
Allow your app on the key
A native app sends no
Originheader, so list the app itself among the key's allowed origins:app:followed by the iOS bundle identifier.Textapp:com.example.shopThe SDK names its app in an
X-Trace-Appheader. Like the web origin check, this decides which apps may use the key; it does not prove the request came from your app. That proof comes from verifying on your server (step 4). - 3
Identify before the action
swiftimport TraceDevice // once, for example in your App or AppDelegate let trace = makeTraceClient(apiKey: "pk_...", endpoint: "https://id.example.com") func checkout() async { var eventId: String? do { eventId = try await trace.get(linkedId: userId, tags: ["action": "checkout"]).eventId } catch let error as IdentifyError { // error.code: timeout, network, invalid_api_key, origin_not_allowed, rate_limited, ... fail open print("Trace unavailable: \(error.code)") } catch {} await api.post("/checkout", ["eventId": eventId as Any]) }Create one client for the app and reuse it. The visitor token is kept in the Keychain, readable after the first unlock and never restored onto another device, so the device is recognised across launches and a new phone is a new device. For consent,
trace.disable()stops collection andtrace.disable(forget: true)also deletes the stored token;trace.enable()resumes.What it reads: the OS version, device model, screen size and scale, physical memory, languages, the IANA time zone, the bundle id, version and build, simulator and jailbreak heuristics, and an install id (
identifierForVendor) hashed with the bundle id so the same phone cannot be matched across different companies' apps. It reads no advertising identifier and does not trigger the App Tracking Transparency prompt. Declare the visitor token as "Device ID" used for fraud prevention in your App Privacy details. - 4
Verify on your server
Anything an app reports can be forged on a rooted or jailbroken device, so decide only from the event your server verifies with the secret key.