iOS Developer Library

Developer

CoreLocation Framework Reference CLBeaconRegion Class Reference

Options
Deployment Target:

On This Page
Language:

CLBeaconRegion

Inheritance


Conforms To


Import Statement


Swift

import CoreLocation

Objective-C

@import CoreLocation;

Availability


Available in iOS 7.0 and later.

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.

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

    Declaration

    Swift

    init!(proximityUUID proximityUUID: NSUUID!, identifier identifier: String!)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    init!(proximityUUID proximityUUID: NSUUID!, major major: CLBeaconMajorValue, identifier identifier: String!)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    init!(proximityUUID proximityUUID: NSUUID!, major major: CLBeaconMajorValue, minor minor: CLBeaconMinorValue, identifier identifier: String!)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var proximityUUID: NSUUID! { get }

    Objective-C

    @property(readonly, nonatomic, strong) NSUUID *proximityUUID

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

  • major major Property

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

    Declaration

    Swift

    var major: NSNumber! { get }

    Objective-C

    @property(readonly, nonatomic, strong) 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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

  • minor minor Property

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

    Declaration

    Swift

    var minor: NSNumber! { get }

    Objective-C

    @property(readonly, nonatomic, strong) 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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var notifyEntryStateOnDisplay: Bool

    Objective-C

    @property(nonatomic, assign) BOOL notifyEntryStateOnDisplay

    Discussion

    When set to YEStrue, 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 NOfalse.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func peripheralDataWithMeasuredPower(_ measuredPower: NSNumber!) -> NSMutableDictionary!

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

Data Types

  • The most significant value in a beacon.

    Declaration

    Swift

    typealias CLBeaconMajorValue = UInt16

    Objective-C

    typedef uint16_t CLBeaconMajorValue;

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

  • The least significant value in a beacon.

    Declaration

    Swift

    typealias CLBeaconMinorValue = UInt16

    Objective-C

    typedef uint16_t CLBeaconMinorValue;

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.