Install SDK
The best way to install the SDK is via CocoaPods or Carthage.For details on the latest SDK releases, see the releases page on GitHub. You can also star ⭐️ and watch 👀 the repo.
CocoaPods
Install CocoaPods. If you don’t have an existingPodfile
, run pod init
in your project directory. Add the following to your Podfile
:
pod install
. You may also need to run pod repo update
.
After installing, use the .xcworkspace
file to open your project in Xcode instead of the .xcproject
file.
Swift Package Manager
In Xcode, go to File > Swift Packages > Add Package Dependency. Enterhttps://github.com/radarlabs/radar-sdk-ios-spm.git
for the Package Repository URL. This URL points to our SPM optimized repo, which has a smaller binary size to facilitate faster build times.
Note: we recommend pinning the minor version you’re installing as we occasionally introduce breaking changes in new minor versions. You can pin the minor version using the range operator:
Only select
RadarSDK
unless you are also intending to use the location metadata feature. Refer to this section for more information.Carthage
Install Carthage. To include Radar as agithub
origin, add the following to your Cartfile
:
binary
origin, add the following to your Cartfile
:
carthage update
and drag Build/iOS/RadarSDK.framework
into the Linked Frameworks and Libraries section of your target. Do not add the framework as an input to your copy-frameworks
run script.
Add manually
You can also add the SDK to your project manually. Download the current release, unzip the package, and dragRadarSDK.xcframework
into your Xcode project. It will automatically appear in the Frameworks, Libraries, and Embedded Content section of your target settings. Switch Do Not Embed to Embed & Sign.
Dependencies
The SDK depends on Apple’sCoreLocation
framework. In your target settings, go to General > Frameworks, Libraries, and Embedded Content and add CoreLocation
if you haven’t already.
The SDK currently supports iOS 10 and higher.
Initialize SDK
When your app starts, initialize the SDK with your publishable API key, found on the Settings page. Use yourTest Publishable
key for testing and non-production environments. Use your Live Publishable
key for production environments.
Note that you should always use your publishable API keys, which are restricted in scope, in the SDK. Do not use your secret API keys, which are unrestricted in scope, in any client-side code.
Request permissions
Radar respects standard iOS location permissions. For foreground tracking or trip tracking with continuous mode, the app’s location authorization status must bekCLAuthorizationStatusAuthorizedWhenInUse
orkCLAuthorizationStatusAuthorizedAlways
. For background tracking or geofencing with responsive mode, the app’s location authorization status must be kCLAuthorizationStatusAuthorizedAlways
.
If your app already requests the necessary location permissions, you can skip this step.
Info.plist
file. For foreground permissions, you must add a value for NSLocationWhenInUseUsageDescription
(Privacy - Location When In Use Usage Description). For background permissions, you must add a value for NSLocationAlwaysAndWhenInUseUsageDescription
(Privacy - Location Always and When In Use Usage Description). These strings are displayed in permissions prompts.

requestWhenInUseAuthorization
on a CLLocationManager
instance. To request background permissions in the app, make sure the user has granted foreground permissions first, then call requestAlwaysAuthorization
on a CLLocationManager
instance.
To request foreground location permissions and then immediately request background location permissions:
Build and run the app to make sure permissions prompts are displayed!
Not seeing permissions prompts? First, make sure your location manager is in memory when you request permissions. Second, make sure you’ve added location usage strings to your
Info.plist
file. Finally, check your device settings to make sure you haven’t already granted location permissionsBackground modes
If you are planning to useRadarTrackingOptions.presetContinuous
or RadarTrackingOptions.presetResponsive
, or if you are planning to range beacons by UUID only, you must enable the Location updates and Background fetch background modes.
In your project settings, go to Signing & Capabilities, add Background Modes, and turn on Location updates and Background fetch.
Note that this requires additional justification during App Store review. Learn more below.

Foreground tracking
Once the user has granted foreground permissions, you can track the user’s location in the foreground. To track the user’s location once in the foreground, call:completionHandler
that receives the request status, the user’s location, the events generated, if any, and the user. The request status can be:
.success
: success.errorPublishableKey
: SDK not initialized.errorPermissions
: location permissions not granted.errorLocation
: location services error or timeout (10 seconds).errorNetwork
: network error or timeout (10 seconds).errorBadRequest
: bad request (missing or invalid params).errorUnauthorized
: unauthorized (invalid API key).errorPaymentRequired
: payment required (organization disabled or usage exceeded).errorForbidden
: forbidden (insufficient permissions).errorNotFound
: not found.errorRateLimit
: too many requests (rate limit exceeded).errorServer
: internal server error.errorUnknown
: unknown error
Build and run the app, then find your user on the Users page! To trigger an event, you’ll need to create a geofence if you haven’t already. Not seeing your user on the Users page? Check
status
in the completionHandler
to see what went wrong.Background tracking for geofencing
Once you have initialized the SDK and the user has authorized background permissions, you can start tracking the user’s location in the background. The SDK supports custom tracking options as well as three presets. For geofencing, we recommend usingRadarTrackingOptions.presetResponsive
. This preset detects whether the device is stopped or moving. When moving, it tells the SDK to send location updates to the server every 2-3 minutes. When stopped, it tells the SDK to shut down to save battery. Once stopped, the device will need to move more than 100 meters to wake up and start moving again.
Assuming the user has authorized background permissions, background tracking will work even if the app has been backgrounded or killed, as iOS location services will wake up the app to deliver events.
Note that location updates may be delayed by if the device has connectivity issues, low battery, or wi-fi disabled.
Though we recommend using presets for most use cases, you can modify the presets. See the tracking options reference.
To test, go for a walk or a drive! Not seeing location updates or events? Remember that, once stopped, the device will need to move more than 100 meters to wake up and start moving again. Also, check your device settings to make sure you’ve granted background location permissions.
Don’t forget! You can always find your user on the Users page or events on the Events page. To trigger an event, you’ll need to create a geofence if you haven’t already.
Background tracking for trips
For trips, we recommend usingRadarTrackingOptions.presetContinuous
. This preset tells the SDK to send location updates to the server every 30 seconds, regardless of whether the device is moving.
By default, this preset shows the flashing blue status bar while tracking. If the flashing blue status bar is shown, only foreground permissions are required for tracking.
startTrip
call:
Not seeing the flashing blue status bar while tracking? Make sure you’ve added the Location updates background mode in your project settings.
Don’t forget! You can always find your user on the Users page or events on the Events page. To trigger an event, you’ll need to create a geofence or start a trip if you haven’t already. Also, check your device settings to make sure you’ve granted location permissions.
Mock tracking for testing
Can’t go for a walk or a drive? You can simulate a sequence of location updates. For example, to simulate a sequence of 10 location updates every 3 seconds by car from an origin to a destination, call:Don’t forget! You can always find your user on the Users page or events on the Events page. To trigger an event, you’ll need to create a geofence if you haven’t already.
Location metadata
The SDK can also pass along information like motion activity detection, speed and heading via the location metadata field. Turn onuseLocationMetadata
in your sdkConfiguration
to enable this feature.
To collect motionActivity, you must include a value for Privacy - Motion Usage Description
in your info.plist
. and install the RadarSDKMotion
companion module. Your app will request permission for Motion Activity data in the first track call.
Add the following to your Podfile
:
RadarSDKMotion
package product to your target via SPM.
Listening for events with a delegate
To listen for events, location updates, and errors client-side, set aRadarDelegate
. Set your RadarDelegate
in a codepath that will be initialized and executed in the background. For example, make your AppDelegate
implement RadarDelegate
, not a ViewController
. AppDelegate
will be initialized in the background, whereas a ViewController
may not be.
The
RadarDelegate
should be instantiated only once and set before tracking begins.To listen for events server-side instead, add a webhook or enable an integration.
Manual tracking
If you want to manage location services yourself, you can manually update the user’s location instead by calling:location
is a CLLocation
instance with a valid latitude, longitude, and horizontal accuracy.
Identify user
The SDK automatically collectsinstallId
(a GUID generated on fresh install) and deviceId
(IDFV).
You can also assign a custom userId
, also called External ID in the dashboard. To set a custom userId
, call:
userId
is a stable unique ID for the user.
Do not send any PII, like names, email addresses, or publicly available IDs, for
userId
. See privacy best practices for more information.metadata
is a dictionary with up to 16 keys and values of type string, boolean, or number.
Finally, to set an optional description for the user, displayed in the dashboard, call:
Debug logging
By default, only critical errors are logged to the console. To enable debug logging, call:AppDelegate
lifecycle methods:
Contact your customer success manager to enable logging app lifecycle events.
Submit to App Store
Apple requires that you justify your use of background location. Add something materially similar to the following to the bottom of your App Store description: This app uses background location to (insert use case here). Continued use of background location may decrease battery life. If you turned on the Location updates background mode, Apple requires additional justification in your App Store review notes. If usingRadarTrackingOptions.presetResponsive
, add something like: This app uses the Radar SDK (https://radar.com) to (insert use case here). The Radar SDK requires the background location mode to support polygon geofences and nearby place detection, which cannot be accomplished with region monitoring or visit monitoring. Or, if using RadarTrackingOptions.presetContinuous
, add something like This app uses the Radar SDK (https://radar.com) to (insert use case here). The Radar SDK requires the location background mode for live trip tracking and live ETAs.
Learn more about this requirement in section 2.5.4 of the App Store Review Guidelines here.
Other APIs
The iOS SDK also exposes APIs for beacons, anonymous context, geocoding, search, and distance.Beacons
If the user has granted location permissions, you can range and monitor beacons. To range beacons in the foreground, call:Get location
Get a single location update without sending it to the server:Context
With the context API, get context for a location without sending device or user identifiers to the server:Geocoding
With the forward geocoding API, geocode an address, converting address to coordinates:Search
With the autocomplete API, autocomplete partial addresses and place names, sorted by relevance:Distance
With the distance API, calculate the travel distance and duration between an origin and a destination:Matrix
With the matrix API, calculate the travel distance and duration between multiple origins and destinations for up to 25 routes:Conversions
With the conversions API, log a conversion, such as a purchase or signup, to analyze alongside your app’s location activity:opened_app
events with a notification that was clicked on to open the app. To set this up automatically, set the relevant flag on the initialization options.