iOS SDK
Set up the Woosmap Geofencing SDK using the iOS SDK
The Woosmap Geofencing SDK allows you to monitor Geofences, track your user’s location and connect with the Woosmap Search and Distance APIs.
Learn how to integrate the iOS SDK below. You can also explore a part of the source code on GitHub to get deeper into how user location is collected.
You can find the Geofencing iOS SDK release notes in the GitHub repository for releases.
Install SDK
You can install the SDK in four different ways. Note that the SDK is small and adds less than 3 MB to your compiled app.
CocoaPods
Install CocoaPods, a dependency manager for Cocoa projects. If you don’t have an existing Podfile, run pod init in your project directory. Add the following to your Podfile:
For usage and installation instructions, visit their website. To integrate Woosmap Geofencing SDK into your Xcode project using CocoaPods, specify it in your Podfile:
use_frameworks!
pod 'WoosmapGeofencing'
Swift Package Manager
In Xcode, go to File > Swift Packages > Add Package Dependency. Enter https://github.com/Woosmap/geofencing-ios-sdk-spm-release.git for the Package Repository URL.
Carthage
Install Carthage. To include GeofenceSDK as a binary origin, add the following to your Cartfile:
binary "https://raw.githubusercontent.com/Woosmap/geofencing-ios-sdk-spm-release/master/WoosmapGeofencing.json" ~> 4.0.0
Then, run carthage update --platform iOS --use-xcframeworks and drag Build/iOS/WoosmapGeofencing.xcframework into the Linked Frameworks and Libraries section of your target. Do not add the framework as an input to your copy-frameworks run script.
Dependencies
The SDK currently supports iOS 13 and higher.
Initialise SDK
Starting from SDK version 4, the WoosmapGeofencing class has been renamed to WoosmapGeofenceManager to prevent conflicts with the package name.
To retrieve your user’s location data when your app starts, follow these steps:
First, set the delegate for the LocationServiceDelegate protocol in the AppDelegate method. (Note: The WoosmapGeofencing SDK must be initialised on the main thread to ensure it can raise events.)
import UIKit
import CoreLocation
import WoosmapGeofencing
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
let dataLocation = DataLocation()
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
WoosmapGeofenceManager.shared.getLocationService().locationServiceDelegate = dataLocation
WoosmapGeofenceManager.shared.setWoosmapAPIKey(key: <<YOUR API KEY>>)
if (CLLocationManager.authorizationStatus() != .notDetermined) {
WoosmapGeofenceManager.shared.startMonitoringInBackground()
}
return true
}
}
In order to avoid losing data, you also need to call startMonitoringInBackground in the proper AppDelegate method:
func applicationDidEnterBackground(_ application: UIApplication) {
if (CLLocationManager.authorizationStatus() != .notDetermined) {
WoosmapGeofenceManager.shared.startMonitoringInBackground()
}
}
To keep the SDK synchronized with the user’s location data, you need to call didBecomeActive in the proper AppDelegate
method too.
func applicationDidBecomeActive(_ application: UIApplication) {
WoosmapGeofenceManager.shared.didBecomeActive()
// Restart any tasks that were paused (or not yet started) while the application was inactive.
// If the application was previously in the background, optionally refresh the user interface.
}
The SDK tracks location by default. To disable location collection, just change the value in the settings of the SDK as follows:
WoosmapGeofenceManager.shared.setTrackingEnable(enable: false)
Finally, to ensure effective retrieval of location data, add this in your class delegate:
public class DataLocation:LocationServiceDelegate {
public init() {}
public func tracingLocation(location: Location) {
NSLog("location: \(location)")
}
public func tracingLocationDidFailWithError(error: Error) {
NSLog("\(error)")
}
public func readLocations()-> [Location] {
return Locations.getAll()
}
public func eraseLocations() {
Locations.deleteAll()
}
}
Usage of CLRegions
The Woosmap Geofencing iOS SDK utilizes CLRegion. To enable all apps to participate in region monitoring, Core Location restricts each app to monitoring up to 20 regions simultaneously. Most Woosmap Geofencing features use between 17 and 20 CLRegion. If you need to reserve some CLRegion slots for other features, specify the number of slots you want to protect:
/// Maximum 3 regions can be released by the Geofencing SDK
WoosmapGeofenceManager.shared.setProtectedRegionSlot(2)
Using Actor
If you implemented the Actor class to separate geofencing logic in a different thread, you still need to initialize WoosmapGeofenceManager.shared and use it on the main thread to make sure the geofencing event is captured.
// MARK: - Actor to handle Woosmap Geofencing setup
actor WoosmapGeofenceActor {
private let dataEvent = DataLocation()
func start() async {
await MainActor.run {
guard let currentProfile = ApplicationData().getProfile() else { return }
let manager = WoosmapGeofenceManager.shared
// Assign delegate
manager.getLocationService().locationServiceDelegate = dataEvent
// Configure Woosmap API
manager.setWoosmapAPIKey(key: WMSettings.shared().key)
// Start passive tracking
manager.startTracking(configurationProfile: .passiveTracking)
// Handle background monitoring
let locationManager = CLLocationManager()
if locationManager.authorizationStatus != .notDetermined {
manager.startMonitoringInBackground()
}
}
}
}
Usage: This keeps actor logic isolated while ensuring all Woosmap calls remain on the main thread.
let worker = WoosmapGeofenceActor()
Task {
await worker.start()
}