These utilities help you track your location when making Amazon Location Service API calls from their iOS applications.
- Go to File -> Add Package Dependencies in your XCode project.
- Type the package URL (https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios/) into the search bar and press the enter key.
- Select the "amazon-location-mobile-tracking-sdk-ios" package and click on "Add Package".
- Select the "AmazonLocationiOSTrackingSDK" package product and click on "Add Package".
These are the functions available from this SDK:
| Class | Function | Description |
|---|---|---|
| LocationTracker | init(identityPoolId: String, trackerName: String, config: LocationTrackerConfig? = nil) | This is an initializer function to create a LocationTracker object. It requires an identityPoolId and trackerName and an optional LocationTrackingConfig. If config is not provided it will be initialized with default values |
| LocationTracker | setTrackerConfig(config: LocationTrackerConfig) | This sets Tracker's config to take effect at any point after initialization of location tracker |
| LocationTracker | getTrackerConfig() -> LocationTrackerConfig | This gets the location tracking config to use or modify in your app |
| LocationTracker | getDeviceId() -> String? | Gets the location tracker's generated device Id |
| LocationTracker | startTracking() | Starts the process of accessing the user's location and sending it to the AWS tracker |
| LocationTracker | resumeTracking() | Resumes the process of accessing the user's location and sending it to the AWS tracker |
| LocationTracker | stopTracking() | Stops the process of tracking the user's location |
| LocationTracker | startBackgroundTracking(mode: BackgroundTrackingMode) | Starts the process of accessing the user's location and sending it to the AWS tracker while the application is in the background.
BackgroundTrackingMode has the following options:
- Active: This option doesn't automatically pauses location updates - BatterySaving: This option automatically pauses location updates - None: This option overall disables background location updates |
| LocationTracker | resumeBackgroundTracking(mode: BackgroundTrackingMode) | Resumes the process of accessing the user's location and sending it to the AWS tracker while the application is in the background. |
| LocationTracker | stopBackgroundTracking() | Stops the process of accessing the user's location and sending it to the AWS tracker while the application is in the background. |
| LocationTracker | getTrackerDeviceLocation(nextToken: String?, startTime: Date? = nil, endTime: Date? = nil, completion: @escaping (Result) -> Void) | Retrieves the uploaded tracking locations for the user's device between start and end date & time |
| LocationTrackerConfig | init() | This initializes the LocationTrackerConfig with default values |
| LocationTrackerConfig | init(locationFilters: [LocationFilter]? = nil, trackingDistanceInterval: Double? = nil, trackingTimeInterval: Double? = nil, trackingAccuracyLevel: Double? = nil, uploadFrequency: Double? = nil, desiredAccuracy: CLLocationAccuracy? = nil, activityType: CLActivityType? = nil, logLevel: LogLevel? = nil) | This initializes the LocationTrackerConfig with user-defined parameter values. If a parameter value is not provided it will be set to a default value |
| LocationFilter | shouldUpload(currentLocation: LocationEntity, previousLocation: LocationEntity?, trackerConfig: LocationTrackerConfig) | The LocationFilter is a protocol that users can implement for their custom filter implementation. A user would need to implement `shouldUpload` function to compare previous and current location and return if the current location should be uploaded |
After installing the library, You will need to add one or both of the following descriptions in info.plist:
- Privacy - Location When In Use Usage Description
- Privacy - Location Always and When In Use Usage Description
Import the Tracking SDK in your class:
import AmazonLocationiOSTrackingSDK
Create LocationTracker and use it with the AWS SDK:
// Create a LocationTracker using an Amazon Cognito Identity Pool ID
let locationTracker = try await LocationTracker(identityPoolId: "<Cognito Identity Pool ID>", trackerName: "<My-tracker-name>")
// Optionally you can set ClientConfig with your own values in either initialize or in a separate function
let trackerConfig = LocationTrackerConfig(locationFilters: [TimeLocationFilter(), DistanceLocationFilter()],
trackingDistanceInterval: 30,
trackingTimeInterval: 30,
logLevel: .debug)
let locationTracker = try await LocationTracker(identityPoolId: "<Cognito Identity Pool ID>", trackerName: "<My-tracker-name>", config: trackerConfig)
locationTracker.setConfig(config: trackerConfig)You can use the location client to make calls to Amazon Location Service. Here are a few simple examples for tracking operations:
// Required in info.plist: Privacy - Location When In Use Usage Description
do {
try locationTracker.startTracking()
} catch TrackingLocationError.permissionDenied {
// Handle permissionDenied by showing the alert message or open the app settings
}
do {
try locationTracker.resumeTracking()
} catch TrackingLocationError.permissionDenied {
// Handle permissionDenied by showing the alert message or open the app settings
}
locationTracker.stopTracking()
// Required in info.plist: Privacy - Location Always and When In Use Usage Description
do {
locationTracker.startBackgroundTracking(mode: .Active) // .Active, .BatterySaving, .None
} catch TrackingLocationError.permissionDenied {
// Handle permissionDenied by showing the alert message or open the app settings
}
do {
locationTracker.resumeBackgroundTracking(mode: .Active)
} catch TrackingLocationError.permissionDenied {
// Handle permissionDenied by showing the alert message or open the app settings
}
locationTracker.stopBackgroundTracking()
// To retrieve device's tracked locations from a tracker
func getTrackingPoints(nextToken: String? = nil) {
let startTime: Date = Date().addingTimeInterval(-86400) // Yesterday's day date & time
let endTime: Date = Date()
locationTracker.getTrackerDeviceLocation(nextToken: nextToken, startTime: startTime, endTime: endTime, completion: { [weak self] result in
switch result {
case .success(let response):
let positions = response.devicePositions
// You can draw positions on map or use it further as per your requirement
// If nextToken is available, recursively call to get more data
if let nextToken = response.nextToken {
self?.getTrackingPoints(nextToken: nextToken)
}
case .failure(let error):
print(error)
}
})
}See CONTRIBUTING for more information.
The best way to interact with our team is through GitHub. You can open an issue and choose from one of our templates for bug reports, feature requests or guidance. If you have a support plan with AWS Support, you can also create a new support case.
Please make sure to check out the following resources before opening an issue:
- Our Changelog for recent changes.
We welcome community contributions and pull requests. See CONTRIBUTING.md for information on how to set up a development environment and submit code.
The Amazon Location Service Mobile Tracking SDK for iOS is distributed under the Apache License, Version 2.0, see LICENSE.txt and NOTICE.txt for more information.