Developer Docs - Mobile Docs - Proximity Attendance

M v7.0C v17.1

Proximity Attendance checks people in and out automatically when they arrive at or leave a location, using small Bluetooth devices called beacons. The person opts in once in the app. After that, their phone records attendance in the background, even when the app is closed.

Beacons broadcast using the iBeacon format, which is the only format iOS can use to wake a closed app. Each broadcast carries three values, and Rock gives each one a meaning:

See Use Proximity Attendance for how to find each value in Rock.

How Detection Works

The phone watches for your organization's UUID, not for individual beacons.

Before You Start

Three things must already be in place, or the commands on this page will run but no attendance will be recorded.

Device Requirements

The phone needs four settings for Proximity Attendance to work. StartBeaconMonitoring walks the person through them, and the core_ProximityAttendanceConfigured merge field is true only when all four are in place.

Notification permission is optional. Without it, attendance is still recorded, but the person will not see the check-in notification.

iOS

Android

Choosing and Configuring Beacons

Any beacon that can broadcast iBeacon with a custom UUID, Major and Minor will work. Beacons are configured over Bluetooth with the manufacturer's app, so check that the app is still available before you buy.

Verifying the UUID. iPhones hide beacon UUIDs from third-party apps, so manufacturer apps on iOS usually show the UUID as blank. To confirm it, use the Beacon Debug View below (it only shows beacons whose UUID matches), or a Bluetooth scanner app on Android.

Disconnect after configuring. Many beacons stop broadcasting normally while a configuration app is connected.

Commands

StartBeaconMonitoring

Starts monitoring for your organization's beacons. The command checks the device settings above and shows only the screens needed to fix what is missing:

If the app was not built with Proximity Attendance enabled, the command shows a "Proximity Attendance Unavailable" alert instead. On iOS it shows the same alert when Background App Refresh is off.

Every screen can be customized with StartBeaconMonitoringCommandParameters. Each View property replaces the default instruction image on that screen.

Properties

StopBeaconMonitoring

Stops all beacon monitoring on the device. Deleting the app also stops monitoring.

Checking Readiness

AppValues.core_ProximityAttendanceConfigured is true when every setting in Device Requirements is in place: location Always, precise location, Bluetooth, and (on iOS) Background App Refresh. It updates as the person changes those settings.

It does not tell you whether monitoring has been started, whether the person is logged in, or whether the app was built with Proximity Attendance. Use it to show or hide a "set up automatic check-in" prompt, not as proof that check-in will succeed.

Check-in Notification

Rock can confirm a proximity check-in with a notification on the phone. The message comes from the Proximity Attendance Notification Template in the check-in configuration, and it is Lava with the new Attendance record available as a merge field.

You're checked in to {{ Attendance.Occurrence.Group.Name }}. Enjoy!

Beacon Debug View

The debug view lists every beacon the phone can hear that broadcasts your organization's UUID, with live signal readings. Use it after installing beacons to check coverage and to confirm each beacon's values. Put it on a page only staff can reach.

If monitoring is not running when the view appears, it starts StartBeaconMonitoring for you. It scans again every 6 seconds; change this with BeaconRangingTimerInterval, in milliseconds.

A beacon that is not listed is either out of range, powered off, or broadcasting a different UUID. Each listed beacon shows:

The colored dot is based on RSSI:

Aim for at least orange everywhere people should be checked in. Distance estimates move around a lot with walls, bodies and phone position, so treat them as a rough guide only.

Planning Your Deployment

Proximity Attendance works best for a building or a few large, well-separated areas, not for individual rooms. These limits are why:

A good first deployment is one beacon per campus entrance or main gathering space, each with its own location, then adding more only where the Beacon Debug View shows gaps.

Troubleshooting

Work from the beacon outward: confirm the phone hears the beacon, then that the phone is set up, then that Rock can match it to a schedule.

Server log. Each proximity request is logged at the Information level with the UUID, whether the person arrived or left, and every beacon's Major, Minor and RSSI. Turn on Information logging for the check-in API to see exactly what a phone sent.