Geofences
Start journeys when users who share their location enter or leave an area you define. Decision record: ADR-0064. You need to enable location sharing first.
Start journeys when users who share their location enter or leave an area you define. Decision record: docs/adr/0064-geofence-tetigi.md. You need to enable location sharing first.
How it works
While the app is open, the SDK sends the location at most once every 5 minutes. The server compares this location with your active geofences and writes an event when a transition occurs:
| Event | Properties |
|---|---|
geofence_enter | geofence_id, geofence_name, detection |
geofence_exit | geofence_id, geofence_name, detection |
No new SDK version or extra permission is needed; it works with every SDK that shares location.
Default behavior: Only locations sent while the app is open are evaluated. Transitions of users whose app is closed are not seen; if the user opens the app while inside a geofence, the entry is created at that moment. To make it work while the app is closed too, enable background monitoring below.
Creating a geofence
Dashboard → Geofences → New geofence:
| Field | Description | Default |
|---|---|---|
| Name | Unique within the app | Required |
| Latitude, longitude | Center point | Required |
| Radius | 100–50,000 meters | 500 |
| Cooldown | Time to wait after the last entry event before a new entry event, 0–10,080 minutes | 60 |
You can define up to 500 geofences per app.
Using it in journeys
In the journey trigger, choose the Event type, then pick the geofence and entry or exit from the Geofence trigger list. The event name and filter are filled in automatically:
{ "kind": "event", "event_name": "geofence_enter", "property_filters": [{ "property": "geofence_id", "op": "eq", "value": "gfn_..." }] }The event must be tied to a user: for a subscription without a known identity, the event is recorded but the journey does not start.
You can also select users who entered a geofence in the last 7 days in a segment:
{ "all": [{ "field": "event", "name": "geofence_enter", "op": "count_gte", "value": 1, "days": 7, "where": { "key": "geofence_id", "value": "gfn_..." } }] }Entry and exit rules
- If the distance to the center is less than or equal to the radius, it counts as an entry.
- For an exit, the distance must exceed the radius by at least 50 meters and at most 200 meters depending on accuracy. This margin prevents GPS jitter from generating constant events at the boundary.
- A location with accuracy worse than 1000 meters does not generate a transition.
- An entry before the cooldown expires does not generate an event, and neither does the exit from that stay.
Background monitoring
Optional, off by default, and available in the native Android and iOS SDKs. Monitoring is done by the operating system. No coordinates are sent to the server; only entering or leaving a geofence is reported.
Decision record: docs/adr/0065-arka-plan-bolge-izleme.md.
Requirements:
- Location sharing must be on (
Location.setShared(true)). - The user must grant background permission.
- The app must call
setGeofencingEnabled(true).
// build.gradle: implementation("com.google.android.gms:play-services-location:21.3.0")
// AndroidManifest.xml: ACCESS_FINE_LOCATION and ACCESS_BACKGROUND_LOCATION
Pushizo.Location.requestBackgroundPermission(activity)
Pushizo.Location.setGeofencingEnabled(true)// Info.plist: NSLocationWhenInUseUsageDescription and NSLocationAlwaysAndWhenInUseUsageDescription
Pushizo.Location.requestAlwaysPermission { granted in
if granted { Pushizo.Location.setGeofencingEnabled(true) }
}What you need to know:
- "Always" location permission requires an additional declaration on the App Store and Google Play, and must also be covered in your privacy notice. The SDK does not add these permissions; you do.
- iOS monitors the nearest 20 geofences, Android the nearest 90. The list is refreshed while the app is open at least every 6 hours, or when the device moves 5 km away.
- On Android, registrations are cleared on reboot and re-created the next time the app opens.
- On devices without Play Services (HMS, ADM) or in apps that do not add the dependency, background monitoring does not start; the trigger that works while the app is open continues.
- The operating system may delay notifications or restrict them in battery saver mode.
- The Flutter, React Native, Capacitor, Cordova, MAUI, Unity and KMP bridges provide
Location.setGeofencingEnabledfrom 0.2.0 onward; permissions and store declarations are managed by the app. There is no background monitoring on Web.
The events' detection property is device for background notifications and location for locations sent while the app is open.
API
curl -X POST "https://api.pushizo.com/v1/apps/$APP_ID/geofences" \
-H "Authorization: Bearer $PUSHIZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Kadıköy mağazası","lat":40.9903,"lng":29.0292,"radius_m":300}'| Endpoint | Scope |
|---|---|
GET /v1/apps/{appId}/geofences, GET .../{geofenceId} | analytics:read |
POST /v1/apps/{appId}/geofences, PATCH and DELETE .../{geofenceId} | admin |
In the response, enter_count and exit_count are total event counts, and inside_count is the number of subscriptions currently known to be inside.
Privacy
Geofence state contains no coordinates. When the user turns off location sharing, geofence states are deleted without generating events, monitoring on the device stops and subsequent notifications are ignored. They are also deleted when the subscription or user is deleted.
Location-based targeting
With the user's permission, you can collect the device location and build segments such as "users within X km of this point" (ADR-0025).
The email channel — SMTP, Amazon SES and Resend providers, sender domain verification, content fields (MJML/HTML, Liquid), open/click tracking, List-Unsubscribe and inbound feedback webhooks.