Skip to content

aws-geospatial/amazon-location-mobile-tracking-sdk-ios

Amazon Location Service Mobile Tracking SDK for iOS

These utilities help you track your location when making Amazon Location Service API calls from their iOS applications.

Installation

  1. Go to File -> Add Package Dependencies in your XCode project.
  2. Type the package URL (https://github.com/aws-geospatial/amazon-location-mobile-tracking-sdk-ios/) into the search bar and press the enter key.
  3. Select the "amazon-location-mobile-tracking-sdk-ios" package and click on "Add Package".
  4. Select the "AmazonLocationiOSTrackingSDK" package product and click on "Add Package".

Functions

These are the functions available from this SDK:

ClassFunctionDescription
LocationTrackerinit(provider: LocationCredentialsProvider, trackerName: String, config: LocationTrackerConfig? = nil)This is an initializer function to create a LocationTracker object. It requires LocationCredentialsProvide and trackerName and an optional LocationTrackingConfig. If config is not provided it will be initialized with default values
LocationTrackersetTrackerConfig(config: LocationTrackerConfig)This sets Tracker's config to take effect at any point after initialization of location tracker
LocationTrackergetTrackerConfig() -> LocationTrackerConfigThis gets the location tracking config to use or modify in your app
LocationTrackergetDeviceId() -> String?Gets the location tracker's generated device Id
LocationTrackerstartTracking()Starts the process of accessing the user's location and sending it to the AWS tracker
LocationTrackerresumeTracking()Resumes the process of accessing the user's location and sending it to the AWS tracker
LocationTrackerstopTracking()Stops the process of tracking the user's location
LocationTrackerstartBackgroundTracking(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
LocationTrackerresumeBackgroundTracking(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.
LocationTrackerstopBackgroundTracking()Stops the process of accessing the user's location and sending it to the AWS tracker while the application is in the background.
LocationTrackergetTrackerDeviceLocation(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
LocationTrackerConfiginit()This initializes the LocationTrackerConfig with default values
LocationTrackerConfiginit(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
LocationFiltershouldUpload(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

Usage

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 AuthHelper in your class:

import AmazonLocationiOSAuthSDK
import AmazonLocationiOSTrackingSDK

Create AuthHelper and use it with the AWS SDK:

// Create an authentication helper using credentials from Cognito
let authHelper = AuthHelper()
let locationCredentialsProvider = authHelper.authenticateWithCognitoUserPool(identityPoolId: "My-Cognito-Identity-Pool-Id", region: "My-region") //example: us-east-1
let locationTracker = LocationTracker(provider: locationCredentialsProvider, 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)
locationTracker = LocationTracker(provider: credentialsProvider, 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)
        }
    })
}

Security

See CONTRIBUTING for more information.

Getting Help

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.

Contributing

We welcome community contributions and pull requests. See CONTRIBUTING.md for information on how to set up a development environment and submit code.

License

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.