CLBeaconRegion Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/CoreLocation.framework
Availability
Available in iOS 7.0 and later.
Companion guide
Declared in
CLBeaconRegion.h

Overview

A CLBeaconRegion object defines a type of region that is based on the device’s proximity to a Bluetooth beacon, as opposed to a geographic location. A beacon region looks for devices whose identifying information matches the information you provide. When that device comes in range, the region triggers the delivery of an appropriate notification.

You can monitor beacon regions in two ways. To receive notifications when a device enters or exits the vicinity of a beacon, use the startMonitoringForRegion: method of your location manager object. While a beacon is in range, you can also call the startRangingBeaconsInRegion: method to begin receiving notifications when the relative distance to the beacon changes.

If you want to configure the current iOS device as a Bluetooth beacon, create a beacon region with the appropriate identifying information. You can then call the peripheralDataWithMeasuredPower: method of the region to get a dictionary that you can use to advertise the device with the Core Bluetooth framework. For more information about using that framework to advertise the device as a beacon, see Location and Maps Programming Guide.

Specifying a Beacon’s Identity

You identify beacons using a combination of three values:

  • The proximityUUID property contains the identifier that you use to identify your company’s beacons. You typically generate only one UUID for your company’s beacons but can generate more as needed. You generate this value using the uuidgen command-line tool.

  • The major property contains a value that can be used to group related sets of beacons. For example, a department store might assign the same major value for all of the beacons on the same floor.

  • The minor property specifies the individual beacon within a group. For example, for a group of beacons on the same floor of a department store, this value might be assigned to a beacon in a particular section.

You program the identity values into the beacon hardware itself using the tools provided by the beacon manufacturer. In your app, you then use those values to identify which beacon was found and respond appropriately.

Tasks

Initializing the Beacon Region

Accessing the Beacon Attributes

Delivering Beacon Notifications

Getting Beacon Advertisement Data

Properties

major

The value identifying a group of beacons. (read-only)

@property (readonly, nonatomic) NSNumber *major
Discussion

If you do not specify a major value for the beacon, the value in this property is nil. When this property is nil, the major value of the beacon is ignored when determining if it is a match.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLBeaconRegion.h

minor

The value identifying a specific beacon within a group. (read-only)

@property (readonly, nonatomic) NSNumber *minor
Discussion

If you do not specify a minor value for the beacon, the value in this property is nil. When this property is nil, the minor value of the beacon is ignored when determining if it is a match.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLBeaconRegion.h

notifyEntryStateOnDisplay

A Boolean indicating whether beacon notifications are sent when the device’s display is on.

@property (nonatomic, assign) BOOL notifyEntryStateOnDisplay;
Discussion

When set to YES, the location manager sends beacon notifications when the user turns on the display and the device is already inside the region. These notifications are sent even if your app is not running. In that situation, the system launches your app into the background so that it can handle the notifications. In both situations, the location manager calls the locationManager:didDetermineState:forRegion: method of its delegate object.

The default value for this property is NO.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLBeaconRegion.h

proximityUUID

The unique ID of the beacons being targeted. (read-only)

@property (readonly, nonatomic) NSUUID *proximityUUID
Availability
  • Available in iOS 7.0 and later.
Declared In
CLBeaconRegion.h

Instance Methods

initWithProximityUUID:identifier:

Initializes and returns a region object that targets a beacon with the specified proximity ID.

- (id)initWithProximityUUID:(NSUUID *)proximityUUID identifier:(NSString *)identifier;
Parameters
proximityUUID

The unique ID of the beacons being targeted. This value must not be nil.

identifier

A unique identifier to associate with the returned region object. You use this identifier to differentiate regions within your application. This value must not be nil.

Return Value

An initialized beacon region object.

Discussion

This method creates a region that results in the reporting of all beacons with the specified proximityUUID value. The major and minor values of the beacons are ignored.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLBeaconRegion.h

initWithProximityUUID:major:identifier:

Initializes and returns a region object that targets a beacon with the specified proximity ID and major value.

- (id)initWithProximityUUID:(NSUUID *)proximityUUID major:(CLBeaconMajorValue)major identifier:(NSString *)identifier;
Parameters
proximityUUID

The unique ID of the beacons being targeted. This value must not be nil.

major

The major value that you use to identify one or more beacons.

identifier

A unique identifier to associate with the returned region object. You use this identifier to differentiate regions within your application. This value must not be nil.

Return Value

An initialized beacon region object.

Discussion

This method creates a region that reports all beacons with the specified proximityUUID and major values. The beacon’s minor value is ignored.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLBeaconRegion.h

initWithProximityUUID:major:minor:identifier:

Initializes and returns a region object that targets a beacon with the specified proximity ID, major value, and minor value.

- (id)initWithProximityUUID:(NSUUID *)proximityUUID major:(CLBeaconMajorValue)major minor:(CLBeaconMinorValue)minor identifier:(NSString *)identifier;
Parameters
proximityUUID

The proximity ID of the beacon being targeted. This value must not be nil.

major

The major value that you use to identify one or more beacons.

minor

The minor value that you use to identify a specific beacon.

identifier

A unique identifier to associate with the returned region object. You use this identifier to differentiate regions within your application. This value must not be nil.

Return Value

An initialized beacon region object.

Discussion

This method creates a region that reports the beacon with the specified proximityUUID, major, and minor values.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLBeaconRegion.h

peripheralDataWithMeasuredPower:

Retrieves data that can be used to advertise the current device as a beacon.

- (NSMutableDictionary *)peripheralDataWithMeasuredPower:(NSNumber *)measuredPower
Parameters
measuredPower

The received signal strength indicator (RSSI) value (measured in decibels) for the device. This value represents the measured strength of the beacon from one meter away and is used during ranging. Specify nil to use the default value for the device.

Return Value

A dictionary of data that you can use in conjunction with a CBPeripheralManager to advertise the current device as a beacon.

Discussion

The returned dictionary encodes the beacon’s identifying information along with other information needed to advertise the beacon. You should not need to access the dictionary contents directly. Pass the dictionary to the startAdvertising: method of a CBPeripheralManager to begin advertising the beacon.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLBeaconRegion.h

Constants

CLBeaconMajorValue

The most significant value in a beacon.

typedef uint16_t CLBeaconMajorValue;
Availability
  • Available in iOS 7.0 and later.
Declared In
CLBeaconRegion.h

CLBeaconMinorValue

The least significant value in a beacon.

typedef uint16_t CLBeaconMinorValue;
Availability
  • Available in iOS 7.0 and later.
Declared In
CLBeaconRegion.h