Oracle Commerce Platform - iBeacon Client Side Framework

iBeacon Client Side Framework

The iBeacon client side framework consists of two major components: detecting iBeacons and fetching iBeacons information from the server. Both functions are handled by the class ATGBeaconManager.

ATGBeacon

The class ATGBeacon represents an iBeacon and encapsulates a Apple CLBeacon class. This class has several properties that can be set directly using a CLBeacon class and several properties that can only be set after fetching information from the server.

Source	Property	Description
Properties taken from `CLBeacon`	UUID	The unique identifier of the iBeacon, used to indicate the company to which the beacon belongs.
	major	The major number of the iBeacon, used to indicate the store to which the beacon belongs.
	minor	the minor number of the iBeacon. We use this number to indicate the aisle or category that the beacon is in
	accuracy	the distance of the iBeacon from the device in meters. If the number is less than 0, then the distance is either unknown or invalid
	proximity - enum CLProximity	The following: `CLProximityUnknown`, `CLProximityImmediate`, `CLProximityNear`, `CLProximityFar` are used to get an estimate of how close the beacon is to the device.
Properties fetched from the server	repositoryId	The repository id of the iBeacon.
	identifier	The iBeacon’s identifier.
	enterAlerts	A list of `ATGBeaconMessages`, the client side representation of `iBeaconAlert`, that should occur when the iBeacon is ranged.
	exitAlerts	A list of `ATGBeaconMessages` that should occur when the iBeacon range is exited.
	store	The store where the iBeacon resides.
	name	The name for the iBeacon.

The methods isEqual: and compare: , which are part of a category called CLBeacon+ATGAdditions, returns what is equal to another CLBeacon if the UUID, major and minor values are the same. CLBeacon+ATGAdditions also implements a hash function to hash all beacons with the same UUID, major and minor to the same values.

Detecting and Ranging iBeacons

The class ATGBeaconManager makes use of Apple’s CoreLocation Framework to monitor and range beacons. ATGBeaconManager simplifies Apple’s framework by only needing UUID, Major and Minor to handle all iBeacon detection internally.. The manager is essentially a black box that removes the need to create any CLLocation objects or worry about location managers, CLLocationManagerDelegates etc.

ATGBeaconManager provides several properties and methods and methods useful for working with iBeacons:

Type	Function/method	Description
Properties	`delegate`	Implements `ATGBeaconManagerDelegate`
Required	didEnterStore:	Called when the UUID, major and minor combination for a detected beacon match a store. Passed an `ATGStore` as a parameter
	didExitStore:	Called when no beacons from the entered store have been ranged in a set timeout. Parameter is the `ATGStore` that was exited.
Methods	getBeaconEnterAlerts	Returns a list of `ATGBeaconMessages` that is a combination of all nearby beacons’ `enterAlerts.`
	getBeaconExitAlerts	Returns a list of `ATGBeaconMessages` that is a combination of all nearby beacons’ `exitAlerts`.
	requestHelp:delegate	Invokes the `requestHelp` REST API with the device id, nearby beacons, and the name entered in the help text box.
	`cancelHelpUsingDelegate:`	Invokes the `cancelHelp` REST API.

ATGBeaconManagerDelegate provides delegate methods for both detecting and ranging beacons and for fetching beacon information. Detection methods are:

Method	Description
`didEnterRegion`	A delegate method called when the `CLBeaconRegion` has been entered. `CLBeaconRegion` has the properties UUID, major and minor. It might, however, make sense if this took UUID, major and minor as parameters instead
`didExitRegion`	A delegate method called when the `CLBeaconRegion` has been exited.
`didRangeBeacons:inRegion`	A delegate method called when the device has ranged beacons inside of a particular region. Is passed a list of `ATGBeacons`

Fetching Beacon Information

ATGBeaconManager also handles REST requests related to iBeacons. All REST methods call corresponding delegate methods on success or failure.

Supported REST calls include:

REST Call	Description
`getUUIDsWithDelegate`	Notifies the delegate of the UUIDs of beacons to should range.
`getBeaconById`	Fetches `ATGBeacon` data from the server using its repository id.
`getStoreForUUID:major:delegate`	Notifies the delegate of the store what the UUID and major combination represent.
`populateBeaconData:delegate`	Populates the beacon parameter’s data by fetching it from the server.
`enteredBeaconRange:delegate`	Called when a beacon is first ranged.
`exitedBeaconRange:delegate`	Called after the store has been exited
`enteredStore:delegate`	Called when you have determined in which store the device is located.
`helpRequested:closestBeacon:forUser:delegate`	Called when the user requests help.
`helpCancelled:delegate`	Called to cancel help request.

The ATGBeaconManager handles all beacon detection internally and provides the methods listed in the previous section.

Copyright © 1997, 2016 Oracle and/or its affiliates. All rights reserved. Legal Notices