Skip to content
Docs menu Mobile apps

iOS

A Swift package that queues events on disk, sends them in batches, and uses the same event names as the web SDK

On this page

Requires iOS 15 or newer and Swift 5.9 or newer.

Install#

In Xcode, choose File > Add Package Dependencies, enter the URL below, and add the SfereAnalytics product to your app target.

Text
https://github.com/sfere-io/sfere-ios-sdk.git

Or add it to Package.swift:

Package.swiftSwift
.package(url: "https://github.com/sfere-io/sfere-ios-sdk.git", from: "0.1.0"),

// in your target's dependencies:
.product(name: "SfereAnalytics", package: "sfere-ios-sdk"),

Set up#

Call setup once, as early as possible in application(_:didFinishLaunchingWithOptions:). Use the source’s browser key: it is public by design. Never put a server key in an app.

AppDelegate.swiftSwift
import SfereAnalytics

let config = SfereConfiguration(
    writeKey: "YOUR_WRITE_KEY",
    host: "https://events.sfere.io"
)
config.consent = ["analytics": true, "advertising": false]   // optional
Sfere.setup(config)

If the key or host is invalid, the SDK logs an error and stays inactive. It never crashes your app.

Option Default What it does
flushAt 20 Events per upload.
flushInterval 30 Seconds between uploads. The SDK also uploads when the app goes to the background.
sessionTimeoutMinutes 30 Inactivity before a new session starts.
trackLifecycleEvents true Sends app_installed, app_opened, app_updated and app_backgrounded.
trackDeepLinks true Sends deep_link_opened from openURL.
consent not set Initial consent categories. Consent saved with setConsent wins.
debug false Prints every payload and validation warning to the console.

Send events#

Use the same GA4 event names as the web. See Track events. Send email and phone as plain values: Sfere hashes them per destination.

Swift
Sfere.shared.identify(userId: "user_1234", traits: ["email": "customer@example.com", "phone": "+15555550123"])
Sfere.shared.screen("Product", properties: ["item_id": "sku_221"])
Sfere.shared.track("add_to_cart", properties: [
    "currency": "USD",
    "value": 149,
    "items": [["item_id": "sku_221", "item_name": "Linen Shirt", "price": 149, "quantity": 1]],
])
Sfere.shared.reset()   // on sign out

Purchases#

Swift
Sfere.shared.purchase(SferePurchase(
    transactionId: "order_98765",
    currency: "USD",
    value: 313,
    items: [SfereItem(itemId: "sku_221", itemName: "Linen Shirt", price: 149, quantity: 1, itemCategories: ["Apparel"])],
    tax: 39,
    shipping: 25,
    dedupId: "order_98765"   // the same value your server sends, if it also reports this purchase
))

Events sent automatically#

The full list, with each event’s properties and what is not tracked, is on Automatic app events.

Event When
app_installed First launch
app_updated First launch of a new version
app_opened Cold start and each return to the foreground
app_backgrounded The app goes to the background
session_started First event of each session
deep_link_opened A link opens the app

Pass every link that opens your app to the SDK. Click IDs (gclid, fbclid, ttclid and others) and UTM values in the link are attached to every event for the rest of the session.

Swift
// UIApplicationDelegate
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    Sfere.shared.openURL(url, options: options)
    return true
}

// SwiftUI
.onOpenURL { url in Sfere.shared.openURL(url) }

For universal links, call Sfere.shared.openURL(url) with userActivity.webpageURL from application(_:continue:restorationHandler:). With scenes, call it from scene(_:openURLContexts:) and scene(_:continue:).

Swift
Sfere.shared.setConsent(["analytics": true, "advertising": true])   // applies from the next event; saved
Sfere.shared.setEnabled(false)   // stops collection and deletes unsent events; saved across launches

Privacy#

  • The package includes a privacy manifest (PrivacyInfo.xcprivacy) that Xcode merges into your app’s privacy report.
  • The SDK does not read the advertising identifier (IDFA), never shows the App Tracking Transparency prompt, and sends no device identifier.