Skip to main content

​
Fantasma iOS SDK

The iOS SDK sources live in sdks/ios/FantasmaSDK, and the repo root publishes them as the FantasmaSDK Swift package.

​
Public API

  • configure(serverURL:writeKey:) async throws
  • track(_:) async throws
  • flush() async throws
  • clear() async

​
Usage

import Foundation
import FantasmaSDK

let serverURL = URL(string: "http://localhost:8081")!

Task {
    do {
        try await Fantasma.configure(
            serverURL: serverURL,
            writeKey: "<ingest-key-from-provision-project>"
        )
        try await Fantasma.track("app_open")
        try await Fantasma.track("screen_view")
        try await Fantasma.flush()
        await Fantasma.clear()
    } catch {
        print("Fantasma SDK error: \(error)")
    }
}
The SDK auto-populates platform, device, app_version, os_version, and locale for each event. Shared ingest and queue behavior lives on the SDK behavior page.

​
Install

Add FantasmaSDK from the repo root package URL: 
https://github.com/RuiAAPeres/fantasma.git
Then use:
  • Package: FantasmaSDK
  • Minimum version: your tagged release, for example 0.4.0
dependencies: [
    .package(url: "https://github.com/RuiAAPeres/fantasma.git", from: "0.4.0"),
]
For local development, you can also use an explicit path to this repository until you have tags available. 
.package(path: "../fantasma"),
Supported platforms:
  • iOS 17.0+
  • macOS 14.0+

​
iOS-Specific Notes

  • The SDK exposes a static Fantasma facade instead of an instance-based client.
  • iPhone emits platform = "ios", device = "phone".
  • iPad emits platform = "ios", device = "tablet".
  • Native macOS, Mac Catalyst, and iOS-on-Mac desktop-class runs emit platform = "macos", device = "desktop".
  • track(_:) throws when the SDK has not been configured.
  • flush() throws when the SDK has not been configured.
  • Reconfiguring to a different server URL or write key discards any still-queued rows after the current upload boundary, even across app relaunches, then switches future uploads to the new destination.
  • In addition to the shared upload triggers, the SDK also attempts uploads when the app enters background.