Article

Using the Visits Location Service

Get location updates in the most power-efficient way, but less frequently than with other services.

Overview

The visits service is the most power-efficient way of gathering location data. With this service, the system delivers location updates only when the user’s movements are noteworthy. Each update includes both the location and the amount of time spent at that location. This service is not intended for navigation or other real-time activities, but you can use to identify patterns in the user’s behavior and apply that knowledge to other parts of your app. For example, a music app might prepare a gym playlist if a user arrives at the gym at their normal workout time.

To start the visits location service, call the startMonitoringVisits() method of your location manager. With this service, the location manager ignores the values in its distanceFilter and desiredAccuracy properties, so you do not need to configure them. The location manager delivers updates to the locationManager(_:didVisit:) method of its delegate. Listing 1 shows how to check for the availability of the visits location service and start it.

Listing 1

Starting the visits location service

func startReceivingVisitChanges() {
    let authorizationStatus = CLLocationManager.authorizationStatus()
    if authorizationStatus != .authorizedAlways {
        // User has not authorized access to location information.
        return
    }
    
    if !CLLocationManager.locationServicesEnabled() {
        // This service is not available.
        return
    }
    locationManager.startMonitoringVisits()
}

Another way to save power is to set the pausesLocationUpdatesAutomatically property of your location manager object to true. Enabling this property lets the system reduce power consumption by disabling location hardware when the user is unlikely to be moving. Pausing updates does not diminish the quality of those updates, but can improve battery life significantly. To help the system determine when to pause updates, you must also assign an appropriate value to the activityType property of your location manager.

Receiving Visit Updates

When you start the visits location service, a recently cached value may be reported to your delegate immediately. As new visit data is obtained, the location manager calls your delegate's locationManager(_:didVisit:) method with the updated value.

Listing 2

Receiving visit updates

func locationManager(_ manager: CLLocationManager, didVisit visit: CLVisit) {
    // Do something with the visit. 
}

Handling Location-Related Errors

When the location manager is unable to deliver location updates, it calls the locationManager(_:didFailWithError:) method of its delegate object. You should always implement this delegate method to handle any errors that might occur. For example, this method is called when the user denies authorization for your app to use location services. In such a scenario, you might want to disable location-related features and notify the user which features are unavailable. You should also stop whatever service you previously started, as demonstrated in Listing 3.

Listing 3

Stopping location services when authorization is denied

func locationManager(_ manager: CLLocationManager,  didFailWithError error: Error) {
   if error.code == .denied {
      // Location updates are not authorized.
      locationManager.stopMonitoringVisits()
      return
   }
   // Notify the user of any errors.
}

See Also

Related Topics

Using the Significant-Change Location Service

Get location updates in a power-friendly way, but less frequently than with the standard location service.

Using the Standard Location Service

Get regular location updates based on the parameters you specify.

Handling Location Events in the Background

Take advantage of background execution modes to respond to location-related events at any time.