Using the Visits Location Service

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.

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.

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.

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

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.

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.
}