Skip to content
Optima docs
SDKsiOS SDK

Installation

iOS SDK v1.4.0 — Installation

Requirements

  • iOS 15.0 floor (Package.swift: .platforms([.iOS(.v15), .macOS(.v12)]) — the .macOS(.v12) entry exists only so the package resolves and the core target type-checks on the Linux/macOS toolchains used in CI and local development; nothing in OptimaSDKUI runs on macOS; the SDK's UI code runs only on iOS).
  • Swift 5.9+ (swift-tools-version:5.9, swiftLanguageVersions: [.v5]).
  • No required third-party dependencies. The core module (OptimaSDK) is Foundation-only: HTTP over URLSession, JSON built and read field-by-field by hand (Internal/Json.swift), storage over UserDefaults and a hand-rolled append-only file outbox. There is no Alamofire, no Codable-based wire model, and no Firebase dependency anywhere in the SDK, including in push — see chapter 7 for why that's safe to say even though the SDK has a push API.
  • The UI module (OptimaSDKUI) additionally links SwiftUI, WebKit (the isolated WKWebView the HTML renderer uses) and SafariServices (SFSafariViewController for outbound links and hosted pages). Skip it entirely if you're going to render content yourself — see chapter 5.

Swift Package Manager, via Xcode

File → Add Package Dependencies…, paste the repository's git URL (https://github.com/MatejBordac/optima-ios-sdk.git), pick a version rule (Up to Next Major, starting at 1.0.0, is the usual choice), and check the OptimaSDK library product for your app target. Check OptimaSDKUI as well if you want the SwiftUI renderers (OptimaHost, OptimaSlot, OptimaRenderer, …) — it depends on OptimaSDK itself, so you never need to add both explicitly, but Xcode's package-product picker still lists each library separately and only adds what you tick.

Swift Package Manager, via Package.swift

For a library target, or if you'd rather manage the dependency as text:

// Package.swift
dependencies: [
    .package(url: "https://github.com/MatejBordac/optima-ios-sdk.git", from: "1.0.0"),
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "OptimaSDK", package: "optima-ios-sdk"),
            .product(name: "OptimaSDKUI", package: "optima-ios-sdk"),   // optional — drop this line to skip the SwiftUI renderers
        ]
    ),
]

CocoaPods

# Podfile
pod 'OptimaSDK', '~> 1.0'
pod 'OptimaSDK/UI', '~> 1.0'   # optional — the SwiftUI renderers subspec

OptimaSDK.podspec declares two subspecs off one pod: Core (the default — everything under Sources/OptimaSDK, plus the privacy manifest resource bundle) and UI (everything under Sources/OptimaSDKUI, depending on OptimaSDK/Core and linking SwiftUI/WebKit/SafariServices). Pulling in pod 'OptimaSDK/UI' is enough on its own — CocoaPods resolves the Core dependency for you — but most Podfiles list both for clarity, exactly mirroring the SPM product list above.

Privacy manifest

Sources/OptimaSDK/Resources/PrivacyInfo.xcprivacy ships as a resource inside the package (resources: [.copy("Resources/PrivacyInfo.xcprivacy")] in Package.swift; the podspec ships it as a resource_bundle for the same reason CocoaPods needs an explicit bundle to embed a resource correctly). Xcode 15+ and App Store Connect both read this automatically once the package is linked — you don't copy or reference it yourself.

What it declares, exactly:

  • NSPrivacyTracking false and an empty NSPrivacyTrackingDomains — the SDK itself contacts only your own Edge endpoint and never the IDFA/ATT APIs (chapter 4).
  • NSPrivacyCollectedDataTypeUserID, linked, not used for tracking, for purposes App Functionality, Analytics and Developer's Advertising or Marketing. This is the SDK's own per-install UUID (_optima_did) — an identifier the SDK assigns, not identifierForVendor and not the advertising identifier, which is why it is declared as a user id rather than as NSPrivacyCollectedDataTypeDeviceID.
  • NSPrivacyCollectedDataTypeProductInteraction, linked, not used for tracking, same purposes — the track/screen hits themselves.
  • NSPrivacyAccessedAPICategoryUserDefaults with reason CA92.1 (the SDK reads and writes only its own com.optima.sdk suite).

Two things are yours, not the SDK's, and are the usual reasons a submission comes back:

  • Operator-configured pixel trackers fire at third-party domains. The tracker inventory (chapter 4) is server-side configuration, so the SDK cannot know those hosts at build time and declares none. If your Optima console has pixel-kind trackers pointed at ad/analytics vendors, your app's own PrivacyInfo.xcprivacy must list those hosts under NSPrivacyTrackingDomains (and set NSPrivacyTracking accordingly) — otherwise those requests are blocked at runtime for users who denied tracking.
  • The declared categories and purposes are a default, not a verdict. They describe what the SDK transmits; what you collect through it (custom props, identifiers passed to identify) and what you do with it server-side can widen them. Have whoever signs off your App Store privacy answers review the list above before your first submission, and add the extra NSPrivacyCollectedDataTypes entries your integration needs to your app's own manifest.

Initializing the SDK

Call Optima.initialize once, as early as possible, on the main thread — it reads UIScreen.main and UIDevice.current while building the device context, which are main-thread-only APIs (both hooks below already run there; if you defer initialization behind your own bootstrap, keep it on the main queue). In a UIKit app, that's AppDelegate.application(_:didFinishLaunchingWithOptions:), before any view controller is presented — so screenTracking = .auto (chapter 2), if you opt into it, catches the very first screen:

import OptimaSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Optima.initialize(try! OptimaConfig(key: "oek_shop_a1b2c3", endpoint: "https://edge.shop.example") {
        $0.debug = true   // wire to your own DEBUG flag in a release build
    })
    return true
}

In a SwiftUI-lifecycle app, App.init() is the equivalent hook:

import SwiftUI
import OptimaSDK

@main
struct MyApp: App {
    init() {
        Optima.initialize(try! OptimaConfig(key: "oek_shop_a1b2c3", endpoint: "https://edge.shop.example"))
    }
    var body: some Scene { WindowGroup { ContentView() } }
}

key and endpoint come from your Optima console: Edge → SDK keys, where you create (or reuse) a key on the mobile platform — see chapter 2 for what that platform distinction controls server-side. OptimaConfig.init throws on a blank key or a non-http(s) endpoint (validated once, at construction — try! is appropriate for a literal, hard-coded configuration; a config built from remote or user-supplied values should try/handle the error instead of crashing on a bad string). Optima.initialize itself never throws: a construction failure inside Platform.makeRuntime leaves Optima.shared on the inert disabled client (see chapter 3) rather than crashing your launch path, and a second call to initialize is a no-op with a warning — the first configuration always wins.

Capturing the launching URL for attribution

Universal links and custom-scheme URLs are the SDK's only source of UTM/click-id attribution on iOS (there is no Play-Install-Referrer equivalent — see chapter 8). Hand the launching URL to captureURL from wherever your app already receives it:

// SwiftUI
WindowGroup { ContentView().onOpenURL { url in Optima.shared.captureURL(url) } }

// UIKit scene delegate
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    URLContexts.first.map { Optima.shared.captureURL($0.url) }
}
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options: UIScene.ConnectionOptions) {
    options.urlContexts.first.map { Optima.shared.captureURL($0.url) }   // cold launch via URL
}

The first capture wins for the life of the process (until reset()) — a second URL, even a different one, is ignored, so calling captureURL from every place a URL can arrive (cold launch and onOpenURL/ openURLContexts while already running) is always safe.

Verifying the install

Set debug = true and watch the Console app / Xcode's device log for the com.optima.sdk subsystem (OSLog, category optima; the SDK falls back to stderr-prefixed optima: lines on non-Darwin platforms, i.e. inside the test container):

log stream --predicate 'subsystem == "com.optima.sdk"' --level debug

On a successful init the SDK's .ready(version) event fires internally (see chapter 3 for how to observe it yourself), and every subsequent track/screen call logs a debug line describing what was enqueued, what was flushed, and any server response. A 401/403 on the first flush almost always means the key is for the wrong platform or has been revoked — see chapter 9. Once you see a successful POST /edge/v1/track in the log, the install is complete and hits are landing.

Other known gaps and parked items are listed in the SDK repository's TODO file.

On this page