Defining a Geographical Region to Be Monitored

To begin monitoring a geographical region, you must define the region and register it with the system. In iOS 7.0 and later, you define geographical regions using the CLCircularRegion class. (In OS X v10.8 and later and in previous versions of iOS, you use the CLRegion class instead.) Each region you create must include both the data that defines the desired geographic area and a unique identifier string. The identifier string is the only guaranteed way for your app to identify a region later. To register a region, call the startMonitoringForRegion: method of your CLLocationManager object.

Listing 2-1 shows a sample method that creates a new geographic region based on a circular overlay region. The overlay’s center point and radius form the boundary for the region, although if the radius is too large to be monitored, it is reduced automatically. You don’t need to save strong references to the regions you create but might want to store the region’s identifier if you plan to access the region information later.

Listing 2-1  Creating and registering a geographical region based on a Map Kit overlay

- (void)registerRegionWithCircularOverlay:(MKCircle*)overlay andIdentifier:(NSString*)identifier {

   // If the overlay's radius is too large, registration fails automatically,

   // so clamp the radius to the max value.

   CLLocationDistance radius = overlay.radius;

   if (radius > self.locManager.maximumRegionMonitoringDistance) {

      radius = self.locManager.maximumRegionMonitoringDistance;

   }

   // Create the geographic region to be monitored.

   CLCircularRegion *geoRegion = [[CLCircularRegion alloc]

      initWithCenter:overlay.coordinate

              radius:radius

          identifier:identifier];

   [self.locManager startMonitoringForRegion:geoRegion];

}

Monitoring of a geographical region begins immediately after registration for authorized apps. However, don’t expect to receive an event right away, because only boundary crossings generate an event. In particular, if the user’s location is already inside the region at registration time, the location manager doesn’t automatically generate an event. Instead, your app must wait for the user to cross the region boundary before an event is generated and sent to the delegate. To check whether the user is already inside the boundary of a region, use the requestStateForRegion: method of the CLLocationManager class.

Be judicious when specifying the set of regions to monitor. Regions are a shared system resource, and the total number of regions available systemwide is limited. For this reason, Core Location limits to 20 the number of regions that may be simultaneously monitored by a single app. To work around this limit, consider registering only those regions in the user’s immediate vicinity. As the user’s location changes, you can remove regions that are now farther way and add regions coming up on the user’s path. If you attempt to register a region and space is unavailable, the location manager calls the locationManager:monitoringDidFailForRegion:withError: method of its delegate with the kCLErrorRegionMonitoringFailure error code.

Handling Boundary-Crossing Events for a Geographical Region

By default, every time a user’s current location crosses a boundary region, the system generates an appropriate region event for your app. Apps can implement the following methods to handle boundary crossings:

• locationManager:didEnterRegion:

• locationManager:didExitRegion:

You can customize which boundary-crossing events notify your app by explicitly setting the notifyOnEntry and notifyOnExit properties of the CLRegion class when you define and register a region. (The default value of both properties is YES.) For example, if you want to be notified only when the user exits the boundary of a region, you can set the value of the region’s notifyOnEntry property to NO.

The system doesn’t report boundary crossings until the boundary plus a system-defined cushion distance is exceeded. This cushion value prevents the system from generating numerous entered and exited events in quick succession while the user is traveling close the edge of the boundary.

When a region boundary is crossed, the most likely response is to alert the user of the proximity to the target item. If your app is running in the background, you can use local notifications to alert the user; otherwise, you can simply post an alert.

Defining a Beacon Region to Be Monitored

To begin monitoring a beacon region, define the region and register it with the system. You define a beacon region with the appropriate initialization method of the CLBeaconRegion class. When you create a CLBeaconRegion object, you specify the proximityUUID, major, and minor properties of the beacons you want to monitor (the proximity UUID is required; the major and minor values are optional). You must also supply a string that uniquely identifies the region so that you can refer to it in your code. Note that a region’s identifier is unrelated to the identifying information that a beacon advertises.

To register a beacon region, call the startMonitoringForRegion: method of your CLLocationManager object. Listing 2-2 shows a sample method that creates and registers a beacon region.

Listing 2-2  Creating and registering a beacon region

- (void)registerBeaconRegionWithUUID:(NSUUID *)proximityUUID andIdentifier:(NSString*)identifier {

   // Create the beacon region to be monitored.

   CLBeaconRegion *beaconRegion = [[CLBeaconRegion alloc]

      initWithProximityUUID:proximityUUID

                 identifier:identifier];

   // Register the beacon region with the location manager.

   [self.locManager startMonitoringForRegion:beaconRegion];

}

As with geographical region monitoring, monitoring of a beacon region begins immediately after registration for authorized apps. When a user’s device detects a beacon that is advertising the identifying information defined by the registered beacon region (proximity UUID, major value, and minor value), the system generates an appropriate region event for your app.

Handling Boundary-Crossing Events for a Beacon Region

When a user enters the registered beacon region, the location manager calls the locationManager:didEnterRegion: of its delegate object. Similarly, when a user is no longer in range of any beacons in the registered beacon region, the location manager calls the locationManager:didExitRegion: of its delegate object. Note that a user must cross the region’s boundary to trigger one of these calls; in particular, the location manager doesn’t call locationManager:didEnterRegion: if the user is already within the region. You can implement these delegate methods to alert the user appropriately or to present location-specific UI.

You can specify which boundary-crossing events should notify your app by setting the notifyOnEntry and notifyOnExit properties of the beacon region. (The default value of both properties is YES.) For example, if you want to be notified only when the user exits the boundary of a region, you can set the value of the region’s notifyOnEntry property to NO.

You can also postpone notifying a user upon entering a beacon region until the user turns on the device’s display. To do so, simply set the value of the beacon region’s notifyEntryStateOnDisplay property value to YES and set the region’s notifyOnEntry property to NO when you register the beacon region. To prevent redundant notifications from being delivered to the user, post a local notification only once per region entry.

// Delegate method from the CLLocationManagerDelegate protocol.

- (void)locationManager:(CLLocationManager *)manager

        didRangeBeacons:(NSArray *)beacons

               inRegion:(CLBeaconRegion *)region {

   if ([beacons count] > 0) {

      CLBeacon *nearestExhibit = [beacons firstObject];

      // Present the exhibit-specific UI only when

      // the user is relatively close to the exhibit.

      if (CLProximityNear == nearestExhibit.proximity) {

         [self presentExhibitInfoWithMajorValue:nearestExhibit.major.integerValue];

      } else {

         [self dismissExhibitInfo];

   }

}

Creating and Advertising a Beacon Region

To use your iOS device as a beacon, you first generate a 128-bit UUID that will be your beacon region’s proximity UUID. Open Terminal and type uuidgen on the command line. You receive a unique 128-bit value in an ASCII string that is punctuated by hyphens, as in this example.

$ uuidgen

39ED98FF-2900-441A-802F-9C398FC199D2

Next, create a beacon region with the UUID you generated for the beacon’s proximity UUID, defining the major and minor values as needed. Be sure to also use a unique string identifier for the new region. This code shows how to create a new beacon region using the example UUID above.

   NSUUID *proximityUUID = [[NSUUID alloc]

      initWithUUIDString:@"39ED98FF-2900-441A-802F-9C398FC199D2"];

   // Create the beacon region.

   CLBeaconRegion *beaconRegion = [[CLBeaconRegion alloc]

      initWithProximityUUID:proximityUUID

                 identifier:@"com.mycompany.myregion"

Now that you have created a beacon region, you need to advertise your beacon’s proximity UUID (and any major or minor value you specified) using the CBPeripheralManager class of the Core Bluetooth framework. In Core Bluetooth, a peripheral is a device that advertises and shares data using Bluetooth low energy. Advertising your beacon’s data is the only way other devices can detect and range your beacon.

To advertise peripheral data in Core Bluetooth, you call the startAdvertising: method of the CBPeripheralManager class on an instance of a CBPeripheralManager object. This method expects a dictionary (an instance of NSDictionary) of advertisement data. As the next example shows, use the peripheralDataWithMeasuredPower: method of the CLBeaconRegion class to receive a dictionary that encodes your beacon’s identifying information along with other information needed for Core Bluetooth to advertise the beacon as a peripheral.

   // Create a dictionary of advertisement data.

   NSDictionary *beaconPeripheralData =

      [beaconRegion peripheralDataWithMeasuredPower:nil];

Next, create an instance of the CBPeripheralManager class, and ask it to advertise your beacon for other devices to detect, as shown in the code below.

   // Create the peripheral manager.

   CBPeripheralManager *peripheralManager = [[CBPeripheralManager alloc]

      initWithDelegate:selfqueue:nil options:nil];

   // Start advertising your beacon's data.

   [peripheralManager startAdvertising:beaconPeripheralData];

After advertising your app as a beacon, your app must continue running in the foreground to broadcast the needed Bluetooth signals. If the user quits the app, the system stops advertising your device as a peripheral.

For more information about how to use a peripheral manager to advertise data using Bluetooth low energy, see CBPeripheralManager Class Reference and Core Bluetooth Programming Guide.