Situm SDK lets you react to geofencing events in two main ways:
- Visually: If you’re using the Situm Map Viewer, it includes a built-in mechanism to show pop-up messages when the user enters a geofence and the app is in the foreground.
- Programmatically: You can subscribe to SDK callbacks to detect geofence entry/exit events, even in the background. Note that background execution has some restrictions (e.g., the app must be running, permissions granted, and OS-specific limitations). More details below.
Visually: Map Viewer pop-ups #
Remember that geofencing-based pop-ups in Situm’s Map Viewer only work when the app is in the foreground (i.e. when the user is activelly using the wayfinding screen).
Situm’s built-in wayfinding UI allows you to show a customizable pop-up message whenever the user enters a geofence. You may configure these messages by modifying your Configuration Profile, in Section Behaviour / Actions (actions allow to trigger certain events when certain conditions are met).
To do so, you need to create a new action of type “Location enters the geofence“, considering the following parametrizations:
- Trigger: allows you to configure when the action will be triggered.
- Enabled: Whether to enable or disable an Action configured for this profile. Default value is true.
- Type: Type of action. Select “Location enters the geofence”. A dropdown menu will appear where you’ll need to select the geofence associated to that action.
- Only once: If checked, the Action will only be triggered once. Default value is true.
- Cooldown (time in seconds): After an Action is triggered, time period during which Actions will not be triggered again. If the “Only once” parameter is false, you can modify this parameter to any value between 0 to 604800 (a week) seconds.
- Action: the action that will be triggered.
- Type: Select “Show a modal”
- Title: The title that will be shown in the pop-up message
- Description: Rich text multi-media information (text, images, video) that will be shown when the user enters the geofence.
You may configure the trigger options (left) and the action options (right) using the Configuration Profile menu under Behaviour / Actions
After you’ve created one or several actions, save your profile. Then, whenever an user enters each of the configured geofences, the pop-up message that you’ve configured will appear.
Programmatically #
You may also want to be aware of users entering and leaving the geofences programmatically. You can trigger any action upon geofence events: vibrations, in-app notifications, backend updates—whatever you need.
Geofencing works in both foreground and background. However, background execution depends on certain conditions: the app must be running, started by the user, and have the necessary permissions. Keep in mind that iOS and Android may still terminate the app (e.g., to save battery). For details, see our background execution documentation.
In order to listen to these interactions you must implement the GeofenceListener interface / delegate (Android, iOS, React Native, Flutter, Cordova/Capacitor). With this interface you will be notified with a list of Geofences (Android, iOS, React Native, Flutter, Cordova/Capacitor) when the user enters or leaves any of them:
Remember to set these listeners before the user starts positioning, it won’t work if you attach it while positioning.
private GeofenceListener geofenceListener = new GeofenceListener() {
@Override
public void onEnteredGeofences(List<Geofence> enteredGeofences) {
Log.d(TAG, "onEnteredGeofences: ");
}
@Override
public void onExitedGeofences(List<Geofence> exitedGeofences) {
Log.d(TAG, "onExitedGeofences: ");
}
};
class MyGeofenceListener: NSObject, SITGeofencesDelegate {
func didEnteredGeofences(_ geofences: [SITGeofence]!) {
print("didEnteredGeofences:")
}
func didExitedGeofences(_ geofences: [SITGeofence]!) {
print("didExitedGeofences:")
}
}
// onEnterGeofences() will return an array with the geofences that the user enters.
// See https://github.com/situmtech/cordova?tab=readme-ov-file#--onentergeofences
cordova.plugins.Situm.onEnterGeofences((enteredGeofences: any) => {
let namesArray: string[] = [];
enteredGeofences.forEach((geofence: any) => {
let geofenceNameWithId = `${geofence.name}(${geofence.identifier})`;
namesArray = [...namesArray, geofenceNameWithId];
});
console.log(`onEnterGeofences: ${namesArray}`);
});
// onExitGeofences() will return an array with the geofences that the user exits.
// See https://github.com/situmtech/cordova?tab=readme-ov-file#--onexitgeofences
cordova.plugins.Situm.onExitGeofences((exitedGeofences: any) => {
let namesArray: string[] = [];
exitedGeofences.forEach((geofence: any) => {
let geofenceNameWithId = `${geofence.name}(${geofence.identifier})`;
namesArray = [...namesArray, geofenceNameWithId];
});
console.log(`onExitGeofences: ${namesArray}`);
});
// onEnterGeofences() will return an array with the geofences that the user enters.
// See https://developers.situm.com/sdk_documentation/react-native/typedoc/classes/default.html#onEnterGeofences
SitumPlugin.onEnterGeofences((enteredGeofences: any) => {
let namesArray: string[] = [];
enteredGeofences.forEach((geofence: any) => {
let geofenceNameWithId = `${geofence.name}(${geofence.identifier})`;
namesArray = [...namesArray, geofenceNameWithId];
});
console.log(`onEnterGeofences: ${namesArray}`);
});
// onExitGeofences() will return an array with the geofences that the user exits.
// See https://developers.situm.com/sdk_documentation/react-native/typedoc/classes/default.html#onExitGeofences
SitumPlugin.onExitGeofences((exitedGeofences: any) => {
let namesArray: string[] = [];
exitedGeofences.forEach((geofence: any) => {
let geofenceNameWithId = `${geofence.name}(${geofence.identifier})`;
namesArray = [...namesArray, geofenceNameWithId];
});
console.log(`onExitGeofences: ${namesArray}`);
});
In order to start using this listener you must attach it to our SDK with the following line of code:
// Make sure you have initialized our SDK with SitumSdk.init(Context) SitumSdk.locationManager().setGeofenceListener(geofenceListener);
SITLocationManager.sharedInstance().addGeofenceDelegate(geofenceDelegate)
// In Cordova this step is not required, we will send you updates as soon as you implement onEnterGeofences() & onExitGeofences() callbacks
// In React Native this step is not required, we will send you updates as soon as you implement onEnterGeofences() & onExitGeofences() callbacks
In case you want to stop this listener, do the following:
SitumSdk.locationManager().setGeofenceListener(null);
SITLocationManager.sharedInstance().removeGeofenceDelegate(geofenceDelegate)
cordova.plugins.Situm.onEnterGeofences(null); cordova.plugins.Situm.onExitGeofences(null);
SitumPlugin.onEnterGeofences(null); SitumPlugin.onExitGeofences(null);
Take in cosideration #
- Positioning geofences (with trainer_metadata custom field) will be ignored by these callbacks. As this type of geofences are used to get better positioning in uncalibrated areas, the entries and exits inside them won’t be notified.
- These callbacks only work with indoor locations. Any outdoor location will produce a call to onExitedGeofences with the last positioned geofences list as parameter.