Location Tracking

Overview

The Radar iOS SDK provides flexible location tracking capabilities, from foreground tracking to continuous background tracking with configurable presets. You can track location once in the foreground, or start background tracking with options optimized for different use cases.

Foreground Tracking

Track the user’s location once in the foreground using trackOnce().

Radar.trackOnce { (status, location, events, user) in
    if status == .success {
        // do something with events, user
    } else {
        // handle error
    }
}

[Radar trackOnceWithCompletionHandler:^(RadarStatus status, CLLocation * _Nullable location, NSArray<RadarEvent *> * _Nullable events, RadarUser * _Nullable user) {
    if (status == RadarStatusSuccess) {
        // do something with events, user
    } else {
        // handle error
    }
}];

Track with Custom Accuracy

You can specify desired accuracy and beacon ranging options:

Radar.trackOnce(desiredAccuracy: .high, beacons: false) { (status, location, events, user) in
    // handle response
}

[Radar trackOnceWithDesiredAccuracy:RadarTrackingOptionsDesiredAccuracyHigh
                            beacons:NO
                  completionHandler:^(RadarStatus status, CLLocation * _Nullable location, NSArray<RadarEvent *> * _Nullable events, RadarUser * _Nullable user) {
    // handle response
}];

Accuracy Options

RadarTrackingOptionsDesiredAccuracyHigh - Uses kCLLocationAccuracyBest
RadarTrackingOptionsDesiredAccuracyMedium - Uses kCLLocationAccuracyHundredMeters (default)
RadarTrackingOptionsDesiredAccuracyLow - Uses kCLLocationAccuracyKilometer

Track with Manual Location

You can manually update the user’s location:

let location = CLLocation(latitude: 40.7128, longitude: -74.0060)

Radar.trackOnce(location: location) { (status, location, events, user) in
    // handle response
}

CLLocation *location = [[CLLocation alloc] initWithLatitude:40.7128 longitude:-74.0060];

[Radar trackOnceWithLocation:location
           completionHandler:^(RadarStatus status, CLLocation * _Nullable location, NSArray<RadarEvent *> * _Nullable events, RadarUser * _Nullable user) {
    // handle response
}];

Manual location tracking calls are subject to rate limits. Use background tracking for continuous location updates.

Background Tracking

Start background tracking with configurable options to monitor location continuously.

Tracking Presets

Radar provides three built-in tracking presets 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.

Radar.startTracking(trackingOptions: .presetContinuous)

[Radar startTrackingWithOptions:RadarTrackingOptions.presetContinuous];

Use Cases: Real-time delivery tracking, ride-sharing, live location sharing

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];

Use Cases: Curbside pickup, fleet tracking, asset tracking

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. Once stopped, the device will need to move several hundred meters and trigger a visit departure to wake up. Lowest battery usage.

Radar.startTracking(trackingOptions: .presetEfficient)

[Radar startTrackingWithOptions:RadarTrackingOptions.presetEfficient];

Use Cases: Store visits, loyalty programs, analytics

Custom Tracking Options

You can create custom tracking options for fine-grained control:

let trackingOptions = RadarTrackingOptions.presetContinuous
trackingOptions.desiredStoppedUpdateInterval = 180 // 3 minutes
trackingOptions.desiredMovingUpdateInterval = 60 // 1 minute
trackingOptions.desiredSyncInterval = 50
trackingOptions.desiredAccuracy = .medium
trackingOptions.stopDuration = 140
trackingOptions.stopDistance = 70
trackingOptions.replay = .stops
trackingOptions.syncLocations = .all
trackingOptions.showBlueBar = false
trackingOptions.useStoppedGeofence = true
trackingOptions.stoppedGeofenceRadius = 100
trackingOptions.useMovingGeofence = false
trackingOptions.syncGeofences = true
trackingOptions.useVisits = false
trackingOptions.useSignificantLocationChanges = false
trackingOptions.beacons = false

Radar.startTracking(trackingOptions: trackingOptions)

RadarTrackingOptions *trackingOptions = RadarTrackingOptions.presetContinuous;
trackingOptions.desiredStoppedUpdateInterval = 180; // 3 minutes
trackingOptions.desiredMovingUpdateInterval = 60; // 1 minute
trackingOptions.desiredSyncInterval = 50;
trackingOptions.desiredAccuracy = RadarTrackingOptionsDesiredAccuracyMedium;
trackingOptions.stopDuration = 140;
trackingOptions.stopDistance = 70;
trackingOptions.replay = RadarTrackingOptionsReplayStops;
trackingOptions.syncLocations = RadarTrackingOptionsSyncAll;
trackingOptions.showBlueBar = NO;
trackingOptions.useStoppedGeofence = YES;
trackingOptions.stoppedGeofenceRadius = 100;
trackingOptions.useMovingGeofence = NO;
trackingOptions.syncGeofences = YES;
trackingOptions.useVisits = NO;
trackingOptions.useSignificantLocationChanges = NO;
trackingOptions.beacons = NO;

[Radar startTrackingWithOptions:trackingOptions];

Tracking Options Reference

Option	Type	Description
`desiredStoppedUpdateInterval`	`int`	Location update interval in seconds when stopped. Use 0 to shut down when stopped.
`desiredMovingUpdateInterval`	`int`	Location update interval in seconds when moving.
`desiredSyncInterval`	`int`	Sync interval in seconds.
`desiredAccuracy`	`RadarTrackingOptionsDesiredAccuracy`	Desired accuracy of location updates (high, medium, low).
`stopDuration`	`int`	Duration in seconds after which the device is considered stopped.
`stopDistance`	`int`	Distance in meters within which the device is considered stopped.
`startTrackingAfter`	`NSDate?`	When to start tracking. Use `nil` to start immediately.
`stopTrackingAfter`	`NSDate?`	When to stop tracking. Use `nil` to track indefinitely.
`replay`	`RadarTrackingOptionsReplay`	Which failed location updates to replay (stops, none, all).
`syncLocations`	`RadarTrackingOptionsSyncLocations`	Which location updates to sync (all, stopsAndExits, none).
`showBlueBar`	`BOOL`	Whether to show the flashing blue status bar when tracking.
`useStoppedGeofence`	`BOOL`	Use iOS region monitoring to create a geofence when stopped.
`stoppedGeofenceRadius`	`int`	Radius in meters of the geofence when stopped.
`useMovingGeofence`	`BOOL`	Use iOS region monitoring to create a geofence when moving.
`movingGeofenceRadius`	`int`	Radius in meters of the geofence when moving.
`syncGeofences`	`BOOL`	Sync nearby geofences from server to improve responsiveness.
`useVisits`	`BOOL`	Use the iOS visit monitoring service.
`useSignificantLocationChanges`	`BOOL`	Use the iOS significant location change service.
`beacons`	`BOOL`	Monitor beacons.
`useMotion`	`BOOL`	Use the iOS motion activity service.
`usePressure`	`BOOL`	Use the iOS pressure service.

Stop Tracking

Stop background tracking:

Radar.stopTracking()

[Radar stopTracking];

Check Tracking Status

Check if tracking has been started:

let isTracking = Radar.isTracking()
print("Tracking status: \(isTracking)")

BOOL isTracking = [Radar isTracking];
NSLog(@"Tracking status: %d", isTracking);

Get Current Tracking Options

Retrieve the current tracking options:

let trackingOptions = Radar.getTrackingOptions()
print("Update interval: \(trackingOptions.desiredMovingUpdateInterval)")

RadarTrackingOptions *trackingOptions = [Radar getTrackingOptions];
NSLog(@"Update interval: %d", trackingOptions.desiredMovingUpdateInterval);

Get Location

Get the device’s current location without tracking:

Radar.getLocation { (status, location, stopped) in
    if status == .success {
        print("Location: \(location)")
    }
}

[Radar getLocationWithCompletionHandler:^(RadarStatus status, CLLocation * _Nullable location, BOOL stopped) {
    if (status == RadarStatusSuccess) {
        NSLog(@"Location: %@", location);
    }
}];

Mock Tracking for Testing

Simulate user movement for testing:

let origin = CLLocation(latitude: 40.7128, longitude: -74.0060)
let destination = CLLocation(latitude: 40.7589, longitude: -73.9851)

Radar.mockTracking(
    origin: origin,
    destination: destination,
    mode: .car,
    steps: 10,
    interval: 3
) { (status, location, events, user) in
    // receive updates at each step
}

CLLocation *origin = [[CLLocation alloc] initWithLatitude:40.7128 longitude:-74.0060];
CLLocation *destination = [[CLLocation alloc] initWithLatitude:40.7589 longitude:-73.9851];

[Radar mockTrackingWithOrigin:origin
                  destination:destination
                         mode:RadarRouteModeCar
                        steps:10
                     interval:3
            completionHandler:^(RadarStatus status, CLLocation * _Nullable location, NSArray<RadarEvent *> * _Nullable events, RadarUser * _Nullable user) {
    // receive updates at each step
}];

Mock tracking is useful for testing geofence entry/exit events and trip tracking during development.

Anonymous Tracking

Enable anonymous tracking to avoid creating user records on the server:

Radar.setAnonymousTrackingEnabled(true)

[Radar setAnonymousTrackingEnabled:YES];

Anonymous tracking avoids sending stable device IDs, user IDs, and user metadata to the server. This limits some functionality but enhances privacy.

Listening for Events

Implement the RadarDelegate protocol to receive location updates and events client-side:

class MyRadarDelegate: NSObject, RadarDelegate {
    func didReceiveEvents(_ events: [RadarEvent], user: RadarUser?) {
        for event in events {
            // handle geofence entry, exit, dwell, etc.
            print("Event type: \(event.type)")
        }
    }
    
    func didUpdateLocation(_ location: CLLocation, user: RadarUser) {
        // location was updated and synced to server
        print("User location: \(location.coordinate)")
    }
    
    func didUpdateClientLocation(_ location: CLLocation, stopped: Bool, source: RadarLocationSource) {
        // location was updated locally (may not be synced)
    }
    
    func didFail(status: RadarStatus) {
        // handle error
    }
}

// Set the delegate
Radar.setDelegate(MyRadarDelegate())

@interface MyRadarDelegate : NSObject <RadarDelegate>
@end

@implementation MyRadarDelegate

- (void)didReceiveEvents:(NSArray<RadarEvent *> *)events user:(RadarUser *)user {
    for (RadarEvent *event in events) {
        // handle geofence entry, exit, dwell, etc.
        NSLog(@"Event type: %ld", (long)event.type);
    }
}

- (void)didUpdateLocation:(CLLocation *)location user:(RadarUser *)user {
    // location was updated and synced to server
    NSLog(@"User location: %@", @(location.coordinate));
}

- (void)didUpdateClientLocation:(CLLocation *)location stopped:(BOOL)stopped source:(RadarLocationSource)source {
    // location was updated locally (may not be synced)
}

- (void)didFailWithStatus:(RadarStatus)status {
    // handle error
}

@end

// Set the delegate
[Radar setDelegate:[[MyRadarDelegate alloc] init]];

Best Practices

Choose the Right Preset

Select a tracking preset based on your use case. Continuous for real-time tracking, Responsive for balanced updates, Efficient for visit-based tracking.

Request Permissions

Request location permissions before starting tracking. Use requestAlwaysAuthorization() for background tracking.

Test with Mock Tracking

Use mock tracking during development to simulate user movement and test your integration.

Monitor Battery Usage

Balance location accuracy and update frequency with battery usage. Use Efficient preset for best battery life.

For more details on tracking, visit the Radar documentation.

Getting Started

Core Features

Location Services

Configuration

Advanced

Migration & Support

Overview

Foreground Tracking

Track with Custom Accuracy

Track with Manual Location

Background Tracking

Tracking Presets

Custom Tracking Options

Tracking Options Reference

Stop Tracking

Check Tracking Status

Get Current Tracking Options

Get Location

Mock Tracking for Testing

Anonymous Tracking

Listening for Events

Best Practices

Choose the Right Preset

Request Permissions

Test with Mock Tracking

Monitor Battery Usage

​Overview

​Foreground Tracking

​Track with Custom Accuracy

​Track with Manual Location

​Background Tracking

​Tracking Presets

​Custom Tracking Options

​Tracking Options Reference

​Stop Tracking

​Check Tracking Status

​Get Current Tracking Options

​Get Location

​Mock Tracking for Testing

​Anonymous Tracking

​Listening for Events

​Best Practices

Choose the Right Preset

Request Permissions

Test with Mock Tracking

Monitor Battery Usage

Overview

Foreground Tracking

Track with Custom Accuracy

Track with Manual Location

Background Tracking

Tracking Presets

Custom Tracking Options

Tracking Options Reference

Stop Tracking

Check Tracking Status

Get Current Tracking Options

Get Location

Mock Tracking for Testing

Anonymous Tracking

Listening for Events

Best Practices