Geo-triggering

Start Geo-triggering

Geo-triggering allows the automatic detection of location context change events (such as entering or exiting a geofence, or crossing a Geoline™). For this capability, the SDK needs to be initialized and the app must have location permission. For many use cases, a foreground service notification is also recommended.

To start Geo-triggering, you should create and start the GeoTriggeringService.

Start with Foreground Service Notification

To achieve optimal performance of the SDK, we recommend initiating the Geo-triggering service with the Foreground Service Notification.

if (ServiceManager.getInstance(context).isBluedotServiceInitialized()) {
    // The Bluedot SDK is initialized, you can start Geo-triggering.

    GeoTriggeringService.builder()
            .notification(notificationReference) // Notification to use to run Geo-triggering as a foreground service.
            .notificationId(myNotificationId) // Optional id to use for foreground service notification. Use if your app will 
                                              // run additional foreground services, or you wish to update the notification.
            .start(myApplicationContext, // This context should be the Application context.
                   error -> {
                       if (error != null) {
                           // Something went wrong when starting Geo-triggering. Handle error here.
                           return;
                       }
                       // Geo-triggering has started successfully. Handle success here.
                   });
} else {
    // The Bluedot SDK is not initialized. Initialize before starting Geo-triggering.
}

Start without the Foreground Service Notification

In scenarios where the Foreground Service Notification is not required, you can start the Geo-triggering service as demonstrated below. For guidance on when to use this approach, please consult your Customer Experience (CX) representative.

if (ServiceManager.getInstance(context).isBluedotServiceInitialized()) {
    // The Bluedot SDK is initialized, you can start Geo-triggering.

    GeoTriggeringService.builder()
        .start(myApplicationContext, // This context should be the Application context.
            error -> {
                if (error != null) {
                    // Something went wrong when starting Geo-triggering. Handle error here.
                    return;
                }
                // Geo-triggering has started successfully. Handle success here.
            });
} else {
    // The Bluedot SDK is not initialized. Initialize before starting Geo-triggering.
}

info

To learn more about the Foreground Service Notification check the Foreground service and persistent notification documentation

Receiving Geo-trigger events

Create a receiver in the Manifest to receive geo-trigger events (such as entering a location):

AndroidManifest

<application android:label="@string/app_name" >
     <receiver
        android:name="my.package.ExampleGeoTriggerReceiver"
        android:enabled="true"
        android:exported="false"
     >
        <intent-filter>
           <action android:name="io.bluedot.point.GEOTRIGGER" />
        </intent-filter>
     </receiver>
 </application>

For every Entry/Exit event generated by BluedotSDK you will receive a callback as onZoneEntryEvent/onZoneExitEvent with GeoTriggerEvent

class ExampleGeoTriggerReceiver : GeoTriggeringEventReceiver() {
    override fun onZoneInfoUpdate(context: Context) {
        // Notification that the local cache of zones has been updated
        // and Zones can be fetched from ServiceManager getZonesAndFences() API
     }

    override fun onZoneEntryEvent(entryEvent: GeoTriggerEvent, context: Context) {
        // Notification that a zone has been entered/Geoline™ crossed.
     }
 
     override fun onZoneExitEvent(exitEvent: GeoTriggerEvent, context: Context) {
        // Notification that an exit detection-enabled zone has been exited.
     }   
 }

info

Exit events will only trigger when the device has moved a substantial distance away from the geofence. Detection of Exit events may not be as immediate as Entry events.

Stop Geo-triggering

If you only need geo-triggering for a limited period, once that period is over, you can stop the geo-trigger service.

GeoTriggeringService.stop(myContext, error -> { 
    if (error != null) {
        // Something went wrong stopping Geo-triggering. Handle error here.
        return;
    }
    
    // Geo-triggering stopped successfully. Handle success here.
});

Geo-triggering start and stop status are provided through callbacks on the  geoTriggeringStatusListener, implemented as lambda functions in the above examples.

Add GeoTriggerEvent class in Proguard

Please add below rule to your ProGuard rules to preserve GeoTriggerEvent parameter names after obfuscation. This is crucial as GeoTriggerEvent is the new payload returned in the Entry and Exit callbacks.

-keep class au.com.bluedot.point.net.engine.event.GeoTriggerEvent {*;}