Configuring Proximity Notifications

Proximity notifications alert customers when they're near one of your outlets by surfacing your loyalty card on their phone's lock screen.

How It Works

When a customer with your wallet pass approaches a configured outlet:

This serves as a passive reminder of your loyalty program and encourages visits — without sending push notifications or draining battery.

Requirements

All four conditions must be met for proximity notifications to work:

Configuring Outlet Locations

1. Go to Outlets and select an outlet.
2. Enter the Latitude and Longitude (decimal format, e.g., -33.8688, 151.2093).
3. Set the Proximity Radius (default: 100 meters).
4. Optionally set the Altitude for multi-level venues.
5. Save your changes.

💡 Tip: Use Google Maps to find exact coordinates — right-click on your location and select "What's here?" to get lat/long values.

Proximity Radius Guidelines

💡 Tip: Start with the default 100-meter radius and adjust based on customer feedback and local geography.

Nearest Outlet Optimization

Cockato automatically calculates the nearest outlets to each location using the Haversine formula. This optimization:

• Ensures wallet passes show the most relevant nearby locations
• Limits to 10 nearest outlets per pass (Apple Wallet maximum)
• Recalculates automatically when outlets are added, moved, or deactivated

Syncing Locations to Wallet Passes

After configuring outlet coordinates:

1. Locations are queued for sync to all customer wallet passes.
2. The sync runs via the refresh-wallet-locations edge function.
3. Check sync status from the Wallet Designer page.
4. The Proximity Status Card shows:
   • Number of outlets with coordinates configured
   • Last sync timestamp
   • Number of passes updated

Triggering a Manual Sync

Location syncs happen automatically when outlet coordinates change. To force a sync:

1. Go to Wallet Designer.
2. Check the proximity status card.
3. If needed, save your wallet design to trigger a full pass update.

Platform-Specific Behavior

Apple Wallet

Google Wallet

Troubleshooting

Notifications not appearing?

• Verify outlet has valid GPS coordinates
• Check that the customer's wallet pass is active
• Ensure device location services are enabled
• Apple: Check that "Suggest on Lock Screen" is enabled for the pass
• Google: Verify notification permissions for Google Wallet

Triggering at wrong locations?

• Verify your GPS coordinates are accurate
• Reduce the proximity radius
• Check for coordinate entry errors (lat/long swapped)

Pass shows wrong number of locations?

• Apple Wallet limits to 10 locations — only the nearest are included
• Deactivated outlets are excluded automatically
• Run a location sync to update passes

Limitations

• Exact triggering depends on the customer's device, OS version, and settings
• Indoor positioning accuracy varies by device
• Customers can disable location suggestions per-pass
• Battery optimization modes may delay or prevent triggers