Geofencing API

Notice!

Geofencing feature is DEPRECATED and not supported from SDK version 13.0.3 onwards.

Since Geofencing feature is deprecated, you might have geo messages table remain on devices database (if you used this feature). To remove the table, you can implement the following code:

    SQLiteDatabase db = this.getWritableDatabase();
    db.execSQL("DROP TABLE IF EXISTS geo_messages");

DEPRECATED

For 5.x version - Geofencing API 5.x

Mobile Messaging Geofencing API is designed and developed to easily enable developers make their application location aware in few steps. Geofencing API will notify the user each time specific geofence area is entered.

To mark a location of interest, you specify its latitude and longitude. To adjust the proximity for the location, you add a radius. The latitude, longitude, and radius define a geofence, creating a circular area, or fence, around the location of interest.

Installation

In order to install Geofencing service, declare an additional dependency in your application's build.gradle file:

dependencies {
    ...
    implementation 'com.infobip:infobip-mobile-messaging-android-geo-sdk:6.+@aar'
}

Check latest version here.

Notice

All required manifest components are merged to application manifest automatically by manifest merger. Please include geo-related components to manifest manually if manifest merger was disabled.

Enabling the Geofencing service

In order to enable the Geofencing service, use the following option:

MobileGeo.getInstance(this).activateGeofencing()

expand to see Java code

MobileGeo.getInstance(this).activateGeofencing();

Geofencing service requires location permission. For Android versions bigger than 6.0 Marshmallow, it's important to request location permission from user manually, or system may throw SecurityException if permission is not accepted already:

• For API > 29 (Android > 10), ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION needs to be requested and if granted then also ACCESS_BACKGROUND_LOCATION
• For API 29 (Android 10) ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION needs to be requested
• For API < 29 (Android < 10) only ACCESS_FINE_LOCATION is required.

Starting from 6.1.0 version you can use MobileMessaging SDK to request permissions automatically - Requesting GEO permissions automatically

Notice - API 29 (Android 10)

For some devices with API 29 (Android 10), geofencing monitoring activation may fail with following error in the console GeofencingImpl: Geofencing monitoring activation failed: Status{statusCode=ERROR, resolution=null}, while only ACCESS_FINE_LOCATION permission used - Google issue. To prevent it try to add also ACCESS_BACKGROUND_LOCATION.

Notice - API 30 (Android 11)

On Android 11 (API level 30) and higher, however, the system dialog doesn't include the Allow all the time option. Instead, users must enable background location on a settings page, as shown below:

Handle area entered event

When geofence area is entered, GeoEvent.GEOFENCE_AREA_ENTERED event is triggered. You can handle geofence area details using Geo object and campaign details using GeoMessage object:

val geofenceAreaEnteredReceiver: BroadcastReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent) {
        val geoMessage: GeoMessage = GeoMessage.createFrom(intent.extras)
        val geo = geoMessage.geo
        // do something...
    }
}

expand to see Java code

private final BroadcastReceiver geofenceAreaEnteredReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        GeoMessage geoMessage = GeoMessage.createFrom(intent.getExtras());
        Geo geo = geoMessage.getGeo();
        // do something...
    }
};

Don't forget to register your BroadcastReceiver to GEOFENCE_AREA_ENTERED event:

val localBroadcastManager = LocalBroadcastManager.getInstance(this)
localBroadcastManager.registerReceiver(geofenceAreaEnteredReceiver,
        IntentFilter(GeoEvent.GEOFENCE_AREA_ENTERED.key))

expand to see Java code

LocalBroadcastManager localBroadcastManager = LocalBroadcastManager.getInstance(this);
localBroadcastManager.registerReceiver(geofenceAreaEnteredReceiver,
        new IntentFilter(GeoEvent.GEOFENCE_AREA_ENTERED.getKey()));

Choose the optimal radius for your geofence

For best results, the minimium radius of the geofence should be set between 100 - 150 meters. When Wi-Fi is available location accuracy is usually between 20 - 50 meters. When indoor location is available, the accuracy range can be as small as 5 meters. Unless you know indoor location is available inside the geofence, assume that Wi-Fi location accuracy is about 50 meters. When Wi-Fi location is not available (for example, when you are driving in rural areas) the location accuracy degrades. The accuracy range can be as large as several hundred meters to several kilometers. In cases like this, you should create geofences using a larger radius.

Taken from: https://developer.android.com/training/location/geofencing.html#BestPractices

Android 13 battery resource optimization

If the user places your app in the "restricted" state for background battery usage, be aware that in case of device being rebooted (system finishes booting) we will not be able to monitor geofencing areas until the "restricted" state is turned off and the app is re-started.

If the user places your app in the "restricted" state for background battery usage while your app targets Android 13, the system doesn't deliver the BOOT_COMPLETED broadcast or the LOCKED_BOOT_COMPLETED broadcast until the app is started for other reasons.

Taken from https://developer.android.com/about/versions/13/behavior-changes-13#performance-battery