Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spotzee.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
https://github.com/spotzee-marketing/ios-sdk
Pick a version range, then add the Spotzee library to your app target.For a Package.swift consumer:
.package(url: "https://github.com/spotzee-marketing/ios-sdk", from: "0.2.0"),

​
Initialise

Call Spotzee.initialize(apiKey:) from application(_:didFinishLaunchingWithOptions:). Use a publishable key (pk_…); read Manage API keys for how to mint one. 
import UIKit
import Spotzee

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Spotzee.initialize(
            apiKey: "pk_…",
            launchOptions: launchOptions
        )
        return true
    }
}
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: 
Spotzee.initialize(
    apiKey: "pk_…",
    inAppDelegate: MyInAppDelegate(),
    launchOptions: launchOptions
)
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.
HeaderValueWhy
AuthorizationBearer <your apiKey>Authenticates the request
Spotzee-Version2026-04-28Pins the API version this SDK release targets
x-spotzee-client-typesdk-iosIdentifies traffic from this SDK. Read Identify your API client type
Content-Typeapplication/jsonSet on POST and PUT requests
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.