Background Modes

The Radar iOS SDK provides powerful background tracking capabilities to monitor user location even when your app is not in the foreground. This guide covers the necessary configuration and implementation details.

Required capabilities

Enable Location Updates background mode

Open your Xcode project and navigate to your app target’s Signing & Capabilities tab.Click the + Capability button and add Background Modes.Enable Location updates to allow the SDK to receive location updates in the background.

Configure Info.plist

Add the required location usage descriptions to your Info.plist:

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We use your location to provide location-based features and notifications.</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location to provide location-based features.</string>

Customize these descriptions to accurately reflect how your app uses location data.

Request location permissions

Request the appropriate location permission level from the user:

import CoreLocation

let locationManager = CLLocationManager()

// Request when-in-use permission first
locationManager.requestWhenInUseAuthorization()

// Then request always authorization for background tracking
locationManager.requestAlwaysAuthorization()

@import CoreLocation;

CLLocationManager *locationManager = [[CLLocationManager alloc] init];

// Request when-in-use permission first
[locationManager requestWhenInUseAuthorization];

// Then request always authorization for background tracking
[locationManager requestAlwaysAuthorization];

Always request WhenInUse permission before requesting Always permission to follow Apple’s recommended flow.

Background tracking presets

Radar provides three preset tracking configurations optimized for different use cases:

Continuous tracking

Updates about every 30 seconds while moving or stopped. Moderate battery usage. Shows the flashing blue status bar during tracking.

import RadarSDK

Radar.startTracking(trackingOptions: .presetContinuous)

@import RadarSDK;

[Radar startTrackingWithOptions:RadarTrackingOptions.presetContinuous];

Responsive tracking

Updates about every 2.5 minutes when moving and shuts down when stopped to save battery. Once stopped, the device will need to move more than 100 meters to wake up and start moving again. Low battery usage.

Radar.startTracking(trackingOptions: .presetResponsive)

[Radar startTrackingWithOptions:RadarTrackingOptions.presetResponsive];

Location updates may be delayed significantly by Low Power Mode, or if the device has connectivity issues, low battery, or Wi-Fi disabled.

Efficient tracking

Uses the iOS visit monitoring service to update only on stops and exits. Lowest battery usage. Once stopped, the device will need to move several hundred meters and trigger a visit departure to wake up.

Radar.startTracking(trackingOptions: .presetEfficient)

[Radar startTrackingWithOptions:RadarTrackingOptions.presetEfficient];

Custom tracking options

For more control, create custom tracking options:

let trackingOptions = RadarTrackingOptions()

// Location update intervals
trackingOptions.desiredStoppedUpdateInterval = 0 // seconds (0 = shut down when stopped)
trackingOptions.desiredMovingUpdateInterval = 150 // seconds
trackingOptions.desiredSyncInterval = 20 // seconds

// Accuracy
trackingOptions.desiredAccuracy = .medium

// Stop detection
trackingOptions.stopDuration = 140 // seconds
trackingOptions.stopDistance = 70 // meters

// Replay failed updates
trackingOptions.replay = .stops

// Sync behavior
trackingOptions.syncLocations = .all

// Background modes
trackingOptions.showBlueBar = false
trackingOptions.useStoppedGeofence = true
trackingOptions.stoppedGeofenceRadius = 100 // meters
trackingOptions.useMovingGeofence = true
trackingOptions.movingGeofenceRadius = 100 // meters
trackingOptions.syncGeofences = true
trackingOptions.useVisits = true
trackingOptions.useSignificantLocationChanges = true

Radar.startTracking(trackingOptions: trackingOptions)

RadarTrackingOptions *trackingOptions = [RadarTrackingOptions new];

// Location update intervals
trackingOptions.desiredStoppedUpdateInterval = 0; // seconds (0 = shut down when stopped)
trackingOptions.desiredMovingUpdateInterval = 150; // seconds
trackingOptions.desiredSyncInterval = 20; // seconds

// Accuracy
trackingOptions.desiredAccuracy = RadarTrackingOptionsDesiredAccuracyMedium;

// Stop detection
trackingOptions.stopDuration = 140; // seconds
trackingOptions.stopDistance = 70; // meters

// Replay failed updates
trackingOptions.replay = RadarTrackingOptionsReplayStops;

// Sync behavior
trackingOptions.syncLocations = RadarTrackingOptionsSyncAll;

// Background modes
trackingOptions.showBlueBar = NO;
trackingOptions.useStoppedGeofence = YES;
trackingOptions.stoppedGeofenceRadius = 100; // meters
trackingOptions.useMovingGeofence = YES;
trackingOptions.movingGeofenceRadius = 100; // meters
trackingOptions.syncGeofences = YES;
trackingOptions.useVisits = YES;
trackingOptions.useSignificantLocationChanges = YES;

[Radar startTrackingWithOptions:trackingOptions];

Background mode options

Blue status bar

The showBlueBar property determines whether the flashing blue status bar is shown when tracking in the background:

trackingOptions.showBlueBar = true // Show blue bar (required for continuous tracking)
trackingOptions.showBlueBar = false // Hide blue bar (use geofencing instead)

Client-side geofencing

Use iOS region monitoring to create client geofences around the device’s current location:

// When stopped
trackingOptions.useStoppedGeofence = true
trackingOptions.stoppedGeofenceRadius = 100 // meters

// When moving
trackingOptions.useMovingGeofence = true
trackingOptions.movingGeofenceRadius = 100 // meters

Visit monitoring

Use the iOS visit monitoring service for lowest battery usage:

trackingOptions.useVisits = true

Learn more about visit monitoring in Apple’s documentation.

Significant location changes

Use the iOS significant location change service:

trackingOptions.useSignificantLocationChanges = true

Learn more about significant location changes in Apple’s documentation.

Geofence syncing

Sync nearby geofences from the server to improve responsiveness:

trackingOptions.syncGeofences = true

Check tracking status

Check whether tracking is currently active:

if Radar.isTracking() {
    print("Tracking is active")
}

if ([Radar isTracking]) {
    NSLog(@"Tracking is active");
}

Get the current tracking options:

let options = Radar.getTrackingOptions()
print("Desired accuracy: \(options.desiredAccuracy)")

RadarTrackingOptions *options = [Radar getTrackingOptions];
NSLog(@"Desired accuracy: %ld", (long)options.desiredAccuracy);

Stop tracking

Stop background tracking:

Radar.stopTracking()

[Radar stopTracking];

Best practices

Request permissions carefully

Follow Apple’s guidelines for requesting location permissions. Always explain why you need the permission before requesting it.

Choose the right preset

Use the preset that matches your use case. Don’t use continuous tracking if responsive or efficient will work.

Test in background

Test your app’s background tracking behavior with the device locked and the app in the background.

Monitor battery usage

Use Xcode’s Energy Log instrument to monitor your app’s battery impact.

Troubleshooting

Background tracking not working

Verify the Location updates background mode is enabled
Ensure you have requested “Always” location authorization
Check that location services are enabled on the device
Verify your Info.plist includes the required usage descriptions

Blue status bar showing unexpectedly

Set showBlueBar to false and use useStoppedGeofence or useMovingGeofence instead for background tracking without the blue bar.

High battery usage

Use .presetResponsive or .presetEfficient instead of .presetContinuous
Increase desiredMovingUpdateInterval and desiredStoppedUpdateInterval
Set desiredAccuracy to .medium or .low
Enable useStoppedGeofence and set desiredStoppedUpdateInterval to 0 to shut down when stopped

Getting Started

Core Features

Location Services

Configuration

Advanced

Migration & Support

Required capabilities

Background tracking presets

Continuous tracking

Responsive tracking

Efficient tracking

Custom tracking options

Background mode options

Blue status bar

Client-side geofencing

Visit monitoring

Significant location changes

Geofence syncing

Check tracking status

Stop tracking

Best practices

Request permissions carefully

Choose the right preset

Test in background

Monitor battery usage

Troubleshooting

​Required capabilities

​Background tracking presets

​Continuous tracking

​Responsive tracking

​Efficient tracking

​Custom tracking options

​Background mode options

​Blue status bar

​Client-side geofencing

​Visit monitoring

​Significant location changes

​Geofence syncing

​Check tracking status

​Stop tracking

​Best practices

Request permissions carefully

Choose the right preset

Test in background

Monitor battery usage

​Troubleshooting

​Related resources

Required capabilities

Background tracking presets

Continuous tracking

Responsive tracking

Efficient tracking

Custom tracking options

Background mode options

Blue status bar

Client-side geofencing

Visit monitoring

Significant location changes

Geofence syncing

Check tracking status

Stop tracking

Best practices

Troubleshooting

Related resources