ax-core-location

Core Location & Spotlight

Quick Patterns

// LOCATION UPDATES (iOS 17+)
Task {
    for try await update in CLLocationUpdate.liveUpdates() {
        if update.authorizationDenied { showManualPicker(); break }
        if update.isStationary { saveLastLocation(update.location); continue }
        if let loc = update.location { process(loc) }
    }
}

// DECLARATIVE AUTH (iOS 18+)
let session = CLServiceSession(authorization: .whenInUse)
// For precise location:
let navSession = CLServiceSession(authorization: .whenInUse, fullAccuracyPurposeKey: "Nav")

// GEOFENCING (iOS 17+)
let monitor = await CLMonitor("Fences")
await monitor.add(
    CLMonitor.CircularGeographicCondition(center: coord, radius: 100),
    identifier: "Target"
)
for try await event in monitor.events {
    if event.state == .satisfied { handleEntry(event.identifier) }
}

// BACKGROUND LOCATION
var bgSession: CLBackgroundActivitySession?  // must be property, not local
bgSession = CLBackgroundActivitySession()    // start from foreground

// GEOCODING
let placemarks = try await CLGeocoder().reverseGeocodeLocation(location)
let city = placemarks.first?.locality

// CORE SPOTLIGHT INDEXING
let attrs = CSSearchableItemAttributeSet(contentType: .item)
attrs.title = "Order #1234"
attrs.contentDescription = "Medium latte"
attrs.keywords = ["coffee", "latte"]
let item = CSSearchableItem(uniqueIdentifier: "order-1234", domainIdentifier: "orders", attributeSet: attrs)
CSSearchableIndex.default().indexSearchableItems([item])

// NSUSERACTIVITY (current screen)
let activity = NSUserActivity(activityType: "com.app.viewOrder")
activity.title = order.name
activity.isEligibleForSearch = true
activity.isEligibleForPrediction = true
activity.persistentIdentifier = order.id.uuidString
activity.becomeCurrent()

Decision Tree

Location task?
|
+-- Need user's position?
|   +-- Continuous tracking? --> CLLocationUpdate.liveUpdates()
|   |   +-- Navigation --> .automotiveNavigation or .otherNavigation
|   |   +-- Fitness --> .fitness
|   |   +-- General --> .default (or omit)
|   +-- One-time location? --> liveUpdates(), take first, cancel Task
|
+-- Geofencing (entry/exit)?
|   --> CLMonitor with CircularGeographicCondition (max 20 conditions)
|   --> Minimum ~100m radius for reliability
|
+-- Beacon proximity?
|   --> CLMonitor with BeaconIdentityCondition
|
+-- Background location?
|   --> CLBackgroundActivitySession (hold as property, start from foreground)
|   --> Background Modes capability: Location updates
|   --> .whenInUse works with CLBackgroundActivitySession (blue indicator)
|
+-- Authorization strategy?
|   +-- Start with .whenInUse (5-10% denial rate)
|   +-- Upgrade to .always only when user triggers background feature
|   +-- NEVER request .always on first launch (30-60% denial rate)
|
+-- Location not working?
    +-- Check authorizationStatus (not .denied or .restricted?)
    +-- Check locationServicesEnabled() system-wide
    +-- Check Info.plist usage description keys present
    +-- Check Task not cancelled/deallocated
    +-- Background: CLBackgroundActivitySession held? Started from foreground?
    +-- Geofence: < 20 conditions? Radius >= 100m? Awaiting monitor.events?

Spotlight / content indexing?
|
+-- Index all app content --> CSSearchableItem (batch)
+-- Current screen activity --> NSUserActivity
+-- App Intents entity --> IndexedEntity + CSSearchableItem(appEntity:)
+-- Handoff between devices --> NSUserActivity.isEligibleForHandoff