Location & Geofencing Reference
Updated March 20, 2026
TL;DR: How to trigger location-based notifications for wallet passes.
- Apple: 10 GPS locations + 10 beacon UUIDs per pass
- Google: 10 locations per class + 10 per object
- Apple supports custom notification text via location.message
- Google controls notification text automatically
- User must enable Location Services for either platform
Overview
This reference covers location-based pass surfacing for Apple Wallet and Google Wallet. When users approach defined locations, their passes automatically appear on the lock screen.
Quick Reference
| Spec | Apple Wallet | Google Wallet |
|---|---|---|
| GPS locations | 10 per pass* | 10 per class + 10 per object* |
| Beacons | 10 per pass** | Not supported |
| Trigger radius | 100m (cards), 1km (tickets) | Google-controlled |
| Custom notification text | Yes (location.message) | No |
| User must enable | Location Services + Wallet | Location Services |
*Basic plan supports 1 location per pass. Enterprise plan supports up to 10 locations.
**Beacons are only available on Enterprise plan.
Apple Wallet
How It Works
- Pass includes (
latitude) and (longitude) coordinates - Device monitors (
location.distance) to those coordinates - When user enters trigger radius, pass surfaces on lock screen
- User sees
location.messagemessage
This is lock screen surfacing, not a push notification. The pass appears automatically based on proximity.
Limits
| Limit | Value |
|---|---|
| Maximum locations per pass | 10 |
| Default trigger radius (loyalty/gift/coupon) | ~100 meters |
| Default trigger radius (event ticket) | ~1 kilometer |
Custom location.distance | May not work below ~100m |
Trigger Radius Behavior
| Pass Type | Default Radius | Rationale |
|---|---|---|
| Loyalty | ~100m | Nearby store reminder |
| Coupon | ~100m | Nearby store reminder |
| Access Control | ~100m | Nearby location |
| Event Ticket | ~1km | Approaching venue |
Location Message Best Practices
| Good | Bad |
|---|---|
| "Store nearby" | "ACME Corp" (already on pass) |
| "Earn double points today" | "Redeem this pass now!" (too salesy) |
| "Show this pass at checkout" | "Don't forget your rewards!" |
Describe why the pass is useful here. Don't repeat your brand name or give instructions.
User Requirements
For location-based surfacing to work, the user must have:
| Requirement | Setting |
|---|---|
| Location Services | Enabled (device-wide) |
| Wallet location access | Enabled (Settings → Privacy → Location → Wallet) |
| Pass location setting | Enabled (on the pass itself) |
Users control all three settings. You cannot force location access.
Apple Wallet — iBeacons
How It Works
- Pass includes beacon UUIDs in
beaconsarray - Device monitors for matching Bluetooth beacons
- When user enters beacon proximity, pass surfaces on lock screen
- Most specific match (UUID + major + minor) determines
location.message
Limits
| Limit | Value |
|---|---|
| Maximum beacon UUIDs per pass | 10 |
| Major/minor combinations | Unlimited (within 10 UUIDs) |
User Requirements
| Requirement | Setting |
|---|---|
| Bluetooth | Enabled |
| Location Services | Enabled |
| Wallet location access | Enabled |
Google Wallet
How It Works
Google uses latitude and longitude coordinates at the class or object level to trigger lock screen surfacing.
Limits
| Limit | Value |
|---|---|
| Locations per class | 10 |
| Locations per object | 10 |
| Total per pass | 20 (class + object combined) |
Behavior
| Aspect | Details |
|---|---|
| Trigger radius | Google-controlled (not configurable) |
| Notification text | Google-controlled (not customizable) |
| Dwell time | Required (user must stay in area) |
Key Differences from Apple
| Feature | Apple Wallet | Google Wallet |
|---|---|---|
| Custom notification text | Yes (location.message) | No |
| Custom trigger radius | Yes (location.distance) | No |
| Beacon support | Yes (iBeacons) | No |
Platform Comparison
Location Capabilities
| Capability | Apple Wallet | Google Wallet |
|---|---|---|
| GPS locations | 10 per pass | 10 per class + 10 per object |
| Beacons | 10 UUIDs | Not supported |
| Custom notification text | Yes | No |
| Custom trigger radius | Yes (limited) | No |
| Altitude support | Yes | No |
Common Mistakes
Exceeding 10 locations (Apple) — Only first 10 are used
Setting location.distance too small (Apple) — Values below ~100m may be ignored
Expecting custom text on Google — Google controls notification content
Forgetting user permissions — Location Services must be enabled by user
Not testing on physical devices — Simulators don't support location triggers
Using beacons without hardware — iBeacons require physical beacon deployment
Including brand name in location.message — Already displayed on pass
Privacy Considerations
What You CAN'T Do
| Limitation | Details |
|---|---|
| Track user location | Location data never leaves device |
| Know when pass surfaces | No callback or analytics |
| Force location access | User controls all permissions |
What You CAN Do
| Capability | Details |
|---|---|
| Define trigger locations | Coordinates stored in pass |
| Define beacon UUIDs | Beacon config stored in pass |
| Customize Apple notification text | Via location.message |