Skip to main content
The iOS SDK is a single Swift framework distributed through Swift Package Manager and CocoaPods. Add it, import Spotzee, and call initialize once from your app delegate.

​
Requirements

  • iOS 13 or later (also runs on Mac Catalyst 13+)
  • Xcode 14 or newer
  • Swift 5.7 or newer

​
Install

In Xcode, open File → Add Package Dependencies and enter:
Pick a version range, then add the Spotzee library to your app target.For a Package.swift consumer:

​
Initialise

Call Spotzee.initialize(apiKey:) from application(_:didFinishLaunchingWithOptions:). Use a publishable key (pk_…); read Manage API keys for how to mint one.
The shared instance is Spotzee.shared. Every other call uses it: Spotzee.shared.identify(…), Spotzee.shared.track(…), and so on. To wire in-app notifications and deeplinks too, pass an inAppDelegate:
Read In-app notifications and deeplinks for the delegate contract.

​
What every request carries

The SDK adds these headers to every API call. You don’t set them yourself. The SDK’s JSONEncoder converts Swift camelCase property names to snake_case before sending, so Identity(externalId:) lands as external_id on the wire.

​
Identity persistence

The SDK persists three values in UserDefaults(suiteName: "Spotzee"):
  • anonymousId: minted on first launch, kept across app launches.
  • externalId: cached after identify succeeds, cleared by reset().
  • deviceId: a per-install UUID used when registering for push.
Call Spotzee.shared.reset() on sign-out to mint a new anonymous ID and clear the cached externalId.

​
Errors

Network failures print a one-line summary to stdout (prefixed SZ |) with the HTTP status, the API error code (when present), the message, and the request_id. Internally the SDK throws a URLError(.badServerResponse) so existing catch blocks keep working. The legacy { error: string } shape and the new RFC 7807 envelope are both parsed; quote request_id to support.

​
Debugging

The SDK does not expose a debug-toggle initialiser. To trace requests in development, attach a Network instrument in Xcode (Debug → Debug Workflow → Capture Network) and filter by host apix.spotzee.com.

​
Next steps

Identify users

Link anonymous activity to a known user.

Track events

Send custom events with properties.

Push notifications

Register for APNs and route incoming pushes through the SDK.

In-app notifications and deeplinks

Render in-app modals and unwrap Universal Links.