This page is part of the Customer.io documentation. For the complete documentation index, see llms.txt.

61

Geofencing

How it works

Geofences let you react when a person enters or exits a real-world location—a store, a venue, a neighborhood. You define geofences in Customer.io. The SDK downloads them, monitors them on the device, and automatically sends a Geofence Transition event to Customer.io when your users cross into (or out of) a geofence. You can use that event to trigger journeys and build segments, the same way you use any other event.

In Customer.io, you group geofences into geofence sets. A geofence set is a group of geofences that you act on together. For example, you might group all of your stores into a geofence set, and trigger a campaign when a person enters any of the geofences in the set. Each Geofence Transition event identifies both the geofence the person crossed and the set it belongs to.

The SDK relies on the operating system’s native geofencing so transitions can arrive while your app is in the background (subject to permissions).

Geofencing depends on the Location module, which supplies the device’s current location. This tells the SDK which geofences to monitor.

Prerequisites

Geofencing requires:

• The Geofence module (io.customer.android:geofence).
• The Location module, which the geofence dependency includes automatically. See location tracking.
• Location permissions from the person using your app.
• Location services enabled on the device.
• Google Play Services on the device.

1. Install the geofence module

Add the geofence dependency to your app’s build.gradle file:

implementation "io.customer.android:geofence:<version-here>"

The geofence dependency includes the location module automatically, so you don’t need to add io.customer.android:location separately. It’s fine to keep an explicit location dependency if you already added one for location tracking.

2. Add location permissions

Add the following permissions to your AndroidManifest.xml and request them from the person using your app:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

How missing permissions affect delivery

3. Initialize the SDK with the geofence module

Register both ModuleLocation and ModuleGeofence when you initialize the SDK. You don’t need to turn on location tracking for geofencing—by default, the geofence module acquires the location it needs on its own. See location modes below.

val builder = CustomerIOConfigBuilder(applicationContext, "your-cdp-api-key")
    // ...
    .addCustomerIOModule(ModuleLocation())
    .addCustomerIOModule(ModuleGeofence())
    .build()

CustomerIO.initialize(builder)

The Geofence Transition event

The SDK sends the Geofence Transition event automatically when a person enters or exits a geofence. You don’t need to track enter or exit transitions yourself.

When a person crosses a geofence, the SDK sends one event for each geofence set the geofence belongs to, each carrying that set’s geosetId. A geofence that isn’t in any geofence set produces a single event without a geosetId.

The event’s timestamp reflects when the user’s device crossed into or out of a geofence, not when the SDK delivered the event. A transition captured while the device isn’t connected to the network still lands on the timeline at the moment it occurred.

Example event:

{
  "name": "Geofence Transition",
  "timestamp": "2026-07-06T17:42:10.482Z",
  "properties": {
    "transition": "enter",
    "geofenceId": "48122",
    "geofenceName": "Downtown flagship store",
    "geosetId": "25678",
    "transitionId": "b3f1c2a4-8e7d-4c2b-9f10-2a6f1e0d5c33",
    "metadata": {
      "region": "northeast",
      "priority": 2
    }
  }
}

Location modes and monitoring

Devices can only monitor a limited number of geofences at once, so the SDK monitors the geofences nearest to the user, ranked by distance from the device’s location. The SDK automatically refreshes that set as the user moves. Geofence sets don’t affect monitoring—the SDK ranks individual geofences, and geofence set membership only determines the events it sends.

The geofence module needs a location fix to select that set. The locationMode in the geofence module’s config controls how it gets one:

ModuleGeofence(
    GeofenceModuleConfig.Builder()
        .setLocationMode(GeofenceLocationMode.AUTOMATIC)
        .build()
)

Location the SDK acquires for geofencing is used for geofencing only—it never produces a Location Update event or updates the person’s profile. It also works independently of the Location module’s tracking mode, even when location tracking is off.

refreshFromCurrentLocation() works in either mode—call it any time you want to force an immediate refresh. Geofences are tied to the identified person, so in MANUAL mode call it after you identify someone; a refresh requested before you identify anyone isn’t retried automatically.

Neither mode limits detection to the moment the SDK acquires a location. Once the SDK registers geofences, the operating system monitors them natively—it wakes your app when the person crosses one, in the background and even between launches, without continuously tracking their location.

Geofence refresh

The SDK re-downloads your geofence definitions from Customer.io—picking up any geofences you’ve added, changed, or removed, along with the geofence sets they belong to, when:

• Your app launches, or you identify a person—at most once every 24 hours. Geofencing needs an identified profile, so if no one is identified when your app launches, the fetch waits until you identify someone.
• The person travels a long distance (about 5 km by default) from where the SDK last fetched.
• Your app forces a refresh by calling refreshFromCurrentLocation().

So changes you make in Customer.io aren’t instant. They reach a device the next time one of these happens—typically within a day for an app in regular use, but longer for an app no one opens.

Duplicate event suppression

The SDK suppresses duplicate enter and exit events for the same geofence within 1 hour. If a device crosses into a geofence, out again, and then crosses back into the geofence within the next hour, the SDK drops the second entrance event.

Limitations

• The SDK doesn’t continuously track the person’s location.
• Geofencing depends on operating-system callbacks.
• Background delivery depends on platform permissions.
• Android geofencing requires Google Play Services.
• Mobile operating systems limit how many geofences an app can monitor at once. If your app uses geofencing from more than one source (for example, Customer.io and another SDK), all monitored geofences share the same operating-system limit. The Customer.io SDK manages its own geofences within that limit, but it can’t control geofences registered by other SDKs or by your app.