Core Location Patterns

Implementation discipline for location features: correct authorization, battery-aware tracking, and reliable background behavior.

Related Skills

• references/api-reference.md - API reference

Anti-Patterns (and cost)

1) Premature Always authorization

// Wrong
manager.requestAlwaysAuthorization()

// Right
CLServiceSession(authorization: .whenInUse)
// upgrade to .always only when user starts background feature

• Cost: fast code, poor adoption (high denial rates)
• Rule: start minimal, escalate with contextual user intent

2) Continuous updates for geofencing

// Wrong: polling location to emulate geofencing
for try await update in CLLocationUpdate.liveUpdates() { ... }

// Right: system geofencing
let monitor = await CLMonitor("Geofences")
await monitor.add(CLMonitor.CircularGeographicCondition(center: target, radius: 100), identifier: "Target")
for try await event in monitor.events { ... }

• Cost: major battery waste
• Rule: use CLMonitor for entry/exit semantics

3) Ignoring stationary behavior

for try await update in CLLocationUpdate.liveUpdates() {
    if let location = update.location { processLocation(location) }
    if update.isStationary { saveLastKnownLocation(update.location) }
}

• Cost: unnecessary processing while stationary
• Rule: respect stationary/pause behavior

4) No graceful denial path

for try await update in CLLocationUpdate.liveUpdates() {
    if update.authorizationDenied { showManualLocationPicker(); break }
    if update.authorizationDeniedGlobally { showSystemLocationDisabledMessage(); break }
    if let location = update.location { processLocation(location) }
}

• Cost: silent failure + broken UX
• Rule: always branch explicit denial states

5) Wrong accuracy for use case

// Wrong for weather app
CLLocationUpdate.liveUpdates(.automotiveNavigation)

// Better by intent
CLLocationUpdate.liveUpdates(.default) // weather/store-finder
CLLocationUpdate.liveUpdates(.fitness) // activity
CLLocationUpdate.liveUpdates(.automotiveNavigation) // turn-by-turn

Use case	Config	Typical accuracy	Battery
Navigation	.automotiveNavigation	~5m	Highest
Fitness	.fitness	~10m	High
Store finder	.default	~10-100m	Medium
Weather	.default	city-level	Low

6) Not stopping updates

private var locationTask: Task<Void, Error>?

func startTracking() {
    locationTask = Task {
        for try await update in CLLocationUpdate.liveUpdates() {
            if Task.isCancelled { break }
            updateMap(update.location)
        }
    }
}

func stopTracking() {
    locationTask?.cancel()
    locationTask = nil
}

• Cost: battery drain + persistent location indicator
• Rule: explicit start/stop lifecycle

7) Ignoring CLServiceSession (iOS 18+)

let session = CLServiceSession(authorization: .whenInUse)
let navSession = CLServiceSession(
    authorization: .whenInUse,
    fullAccuracyPurposeKey: "Navigation"
)

for try await diag in session.diagnostics {
    if diag.authorizationDenied { handleDenial() }
}

• Cost: manual state machine complexity
• Rule: declare needs; observe diagnostics

Decision Trees

Authorization

1. Need background location?

• no -> .whenInUse
• yes -> start .whenInUse, upgrade .always at first background feature action

2. Need precise location?

• always -> full accuracy purpose key
• sometimes -> temporary full-accuracy session only during relevant feature

Monitoring mode

1. Track continuous position?

• use CLLocationUpdate.liveUpdates() with matching LiveConfiguration

2. Entry/exit geofence?

• use CLMonitor.CircularGeographicCondition (20-condition cap)

3. Beacon proximity?

• use CLMonitor.BeaconIdentityCondition with needed granularity

4. Low-power broad movement only?

• use significant-change monitoring (legacy API)

Accuracy selection

• pick lowest accuracy that still satisfies feature requirements
• high speed driving -> .automotiveNavigation
• walking/cycling -> .otherNavigation
• general/stationary -> .default

Higher accuracy always increases energy cost.

Pressure Scenarios

"Request Always on first launch"

Response:

• upfront Always requests commonly increase denial
• use staged ask: .whenInUse first, upgrade on feature trigger
• reference CLServiceSession guidance for contextual asks

"Background location not working"

Checklist:

1. background capability present
2. CLBackgroundActivitySession retained
3. session started in foreground
4. relaunch recovery restores session + update stream

"Geofence unreliable in production"

Checklist:

1. <=20 conditions
2. radius >=100m
3. always await monitor.events
4. recreate monitor on app launch
5. inspect lastEvent and accuracyLimited

Pre-Release Checklist

Info.plist

• NSLocationWhenInUseUsageDescription
• NSLocationAlwaysAndWhenInUseUsageDescription (if applicable)
• NSLocationDefaultAccuracyReduced (if acceptable)
• NSLocationTemporaryUsageDescriptionDictionary (if requesting temporary full accuracy)
• UIBackgroundModes includes location (if background tracking)

Authorization and UX

• Start with minimal auth
• Upgrade only at feature trigger
• Denial and global-disable paths handled
• Reduced-accuracy path tested

Runtime lifecycle

• Appropriate LiveConfiguration
• Stationary behavior handled
• Tasks canceled when inactive
• Geofencing not implemented via continuous polling

Testing

• Deny/re-enable flow tested
• Background/foreground transitions tested
• Termination + relaunch recovery tested

Background Location Checklist

Setup

• Capability enabled: Location updates
• CLBackgroundActivitySession retained strongly
• Created in foreground
• Relaunch path rehydrates tracking state

Lifecycle

• Persist "tracking active" state
• Restore session and update stream on launch
• Reinitialize CLMonitor with same name

Version Guidance

Feature	Minimum iOS	Note
CLLocationUpdate	17	AsyncSequence API
CLMonitor	17	Region/beacon monitoring
CLBackgroundActivitySession	17	Background with indicator
CLServiceSession	18	Declarative authorization

• iOS 14-16: use CLLocationManager delegate style.
• iOS 17+: prefer CLLocationUpdate and CLMonitor.
• iOS 18+: add CLServiceSession.

Resources

• WWDC: 2023-10180, 2023-10147, 2024-10212
• Docs: /corelocation, /corelocation/clmonitor, /corelocation/cllocationupdate, /corelocation/clservicesession
• Reference: references/api-reference.md