The GeoSpark iOS SDK makes it quick and easy to build a location tracker for your iOS app. We provide powerful and customizable tracking modes and features that can be used to collect your users’ location updates.
To use the GeoSpark SDK, the following things are required:
Get yourself a free GeoSpark Account. No credit card required.
Create a project and add an iOS app to the project.
You need the SDK_KEY in your project settings which you’ll need to initialize the SDK.
Now you’re ready to integrate the SDK into your iOS application.
The GeoSpark iOS SDK requires Xcode 10.0 or later and it compatible with apps targeting iOS version 10 and above
To integrate the GeoSpark SDK, you need a GeoSpark account.
Go to Xcode > File > New Project
Configure the information property list file Info.plist
with an XML snippet that contains data about your app. You need to add strings for NSLocationWhenInUseUsageDescription
in the Info.plist
file to prompt the user during location permissions for foreground location tracking.
For background location tracking, you also need to add a string for NSLocationAlwaysUsageDescription
and NSLocationAlwaysAndWhenInUseUsageDescription
in the same Info.plist
file.
<key>NSLocationWhenInUseUsageDescription</key><string>Add description for foreground only location usage.</string><key>NSLocationAlwaysUsageDescription</key><string>Add description for background location usage. iOS 10 and below"</string><key>NSLocationAlwaysAndWhenInUseUsageDescription</key><string>Add description for background location usage. iOS 11 and above</string>
Next you need to enable
Background fetch
and Location updates
under Project Setting
> Capabilities
> Background Modes
.
Follow the steps below to add the SDK to the project using CocoaPods. Add the below to the Podfile
pod 'GeoSpark'
Then run pod install
.
This will add the GeoSpark SDK and its dependencies to your project. The GeoSpark SDK depends on CoreLocation
, AWSMobileClient
and AWSIoT
for fetching locations and its transmission to our servers. The SDK supports iOS 10 and above.
If you’re not familiar with using Cocoapods or prefer manual installation, we’ve added a ZIP file to the SDK. Use this link to download the GeoSpark.framework.zip file.
Unzip the file and add the GeoSpark SDK GeoSpark.framework
to your Xcode project by dragging the file into your Project Navigator.
You can do this by selecting the project file in the navigator on the left side of the Xcode window, and then navigating to the Linked Frameworks and Libraries section. From there, click the “+” button to add the GeoSpark framework.
Add the following code in AppDelegate.
. This code imports the SDK and allows the SDK to use other methods.
import GeoSpark
After import, add the below code under application(_:didFinishLaunchingWithOptions:)
in your AppDelegate
class. The SDK must be initialized before calling any of the other SDK methods using your project's SDK key.
GeoSpark.initialize("YOUR-SDK-KEY-GOES-HERE")
Once the SDK is initialised, you need to create or get a user to start the tracking and use other methods. Every user created will have a unique GeoSpark identifier which will be used to login and access developer APIs. We call this GeoSpark user_Id
.
GeoSpark.createUser("SET-USER-DESCRIPTION-HERE") { (geosparkUser, error) in// access geospark user id with geosparkUser?.userId// access geospark user description with geosparkUser?.userDescription// access geospark error code with error?.code// access geospark error message with error?.message}
The option user description can be used to update user information such as name, address or add an existing user ID. Make sure the information is encrypted if you are planning to save personal information like an email or phone number.
You can always set or update user descriptions later using the below code.
GeoSpark.setDescription("SET-USER-DESCRIPTION-HERE")
If you already have a GeoSpark user_ID
which you would like to reuse instead of creating a new user, use the code below to get a user session.
GeoSpark.getUser("GEOSPARK USER ID") { (geosparkUser, error) in// access geospark user id with geosparkUser?.userId// access geospark user description with geosparkUser?.userDescription// access geospark user description with error?.code// access geospark user description with error?.message}
Now that the location tracking is set up, you can subscribe to locations and events and use the data locally on your device or send it directly to your own backend server.
To do that, you need to toggle the location and event listener to true
. By default, the status will set to false
and needs to be set to true
in order to stream the location and events updates to the same device or other devices.
GeoSpark.toggleListener(Events: true, Locations: true) { (geosparkUser, error) in// access location lister status with geosparkUser?.locationListener// access events lister status geosparkUser?.eventListener// access geospark error code with error?.code// access geospark error message with error?.message}
Before you start location tracking, you need to get permission from the user for your application to access locations.
Import CoreLocation
at the top of the AppDelegate
. file.
import CoreLocation
2. Make the below class declaration for Location Manager.
let locationManager = CLLocationManager()
3. Open AppDelegate.
and add this line before the return statement in application(_:didFinishLaunchingWithOptions:).
With this line, you ask users to allow the app to access location data both in the background and the foreground.
locationManager.requestLocation()
GeoSpark.startTracking(TrackingMode)
Use the tracking modes while you use the startTracking method GeoSpark.startTracking
You can now start tracking your users. GeoSpark has three default tracking modes along with a custom version. They are different based on the frequency of location updates and battery consumption. The higher the frequency, the higher the battery consumption.
Mode | Battery usage | Updates every | Optimised for/advised for |
Active | 6% - 12% | 25 ~ 250 meters | Ride Hailing / Sharing |
Balanced | 3% - 6% | 50 ~ 500 meters | On Demand Services |
Passive | 0% - 1% | 100 ~ 1000 meters | Social Apps |
//active trackingGeoSpark.startTracking(GeoSparkTrackingMode.active);// balanced trackingGeoSpark.startTracking(GeoSparkTrackingMode.balanced);// passive trackingGeoSpark.startTracking(GeoSparkTrackingMode.passive);
The SDK also provides a custom tracking mode which allows you to customize and build your own tracking mode as per your requirement.
Type | Unit | Unit Range |
Distance Interval | Meters | 1m ~ 2500m |
Distance between location updates example code:
// define a custom tracking methodlet trackingMethod = GeoSparkTrackingMethods.custom// update the settings for the created method as per needtrackingMethod.activityType = .fitnesstrackingMethod.pausesLocationUpdatesAutomatically = truetrackingMethod.showsBackgroundLocationIndicator = truetrackingMethod.distanceFilter = 10trackingMethod.useSignificantLocationChanges = falsetrackingMethod.useRegionMonitoring = falsetrackingMethod.useVisits = falsetrackingMethod.useSignificantLocationChanges = falsetrackingMethod.desiredAccuracy = .nearestTenMetersGeoSpark.startTracking(.custom, options: trackingMethod)
Time between location updates example code:
// define a custom tracking methodlet trackingMethod = GeoSparkTrackingMethods.customtrackingMethod.allowBackgroundLocationUpdates = truetrackingMethod.desiredAccuracy = kCLLocationAccuracyBest// Update interval in secondstrackingMethod.updateInterval = 10GeoSpark.startTracking(.custom, options: trackingMethod)
To stop the tracking use the below method.
GeoSpark.stopTracking()
It will publish location data and these data will be sent to Roam servers for further processing and data will be saved in our database servers.
var geoSparkPublish = GeoSparkPublish()GeoSpark.publishSave(geoSparkPublish)
To stop publishing the location data to other clients.
GeoSpark.stopPublishing();
Now that you have enabled the location listener, use the below method to subscribe to your own or other user's location updates and events.
GeoSpark.subscribe(TYPE, "USER-ID");
GeoSpark.unSubscribe(TYPE, "USER-ID");
Type | Description |
GeoSparkSubscribe.Events | Subscribe to your own events. |
GeoSparkSubscribe.Location | Subscribe to your own location (or) other user's location updates. |
GeoSparkSubscribe.Both | Subscribe to your own events and location (or) other user's location updates. |