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 inOptimaSDKUIruns 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 overURLSession, JSON built and read field-by-field by hand (Internal/Json.swift), storage overUserDefaultsand a hand-rolled append-only file outbox. There is no Alamofire, noCodable-based wire model, and no Firebase dependency anywhere in the SDK, including inpush— see chapter 7 for why that's safe to say even though the SDK has a push API. - The UI module (
OptimaSDKUI) additionally linksSwiftUI,WebKit(the isolatedWKWebViewthe HTML renderer uses) andSafariServices(SFSafariViewControllerfor 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 subspecOptimaSDK.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:
NSPrivacyTrackingfalseand an emptyNSPrivacyTrackingDomains— 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, notidentifierForVendorand not the advertising identifier, which is why it is declared as a user id rather than asNSPrivacyCollectedDataTypeDeviceID.NSPrivacyCollectedDataTypeProductInteraction, linked, not used for tracking, same purposes — thetrack/screenhits themselves.NSPrivacyAccessedAPICategoryUserDefaultswith reasonCA92.1(the SDK reads and writes only its owncom.optima.sdksuite).
Two things are yours, not the SDK's, and are the usual reasons a submission comes back:
- Operator-configured
pixeltrackers 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 haspixel-kind trackers pointed at ad/analytics vendors, your app's ownPrivacyInfo.xcprivacymust list those hosts underNSPrivacyTrackingDomains(and setNSPrivacyTrackingaccordingly) — 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 extraNSPrivacyCollectedDataTypesentries 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 debugOn 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.