PushizoDocs
Channels

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:

EventProperties
geofence_entergeofence_id, geofence_name, detection
geofence_exitgeofence_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:

FieldDescriptionDefault
NameUnique within the appRequired
Latitude, longitudeCenter pointRequired
Radius100–50,000 meters500
CooldownTime to wait after the last entry event before a new entry event, 0–10,080 minutes60

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:

  1. Location sharing must be on (Location.setShared(true)).
  2. The user must grant background permission.
  3. 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.setGeofencingEnabled from 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}'
EndpointScope
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.

On this page