Smart Geofences

---

To learn about the Smart Geofences feature, check out this page. Smart Geofences can be configured for an entire population, but not at the individual user level. At the moment, creating geofences directly through the SDK is not supported. Instead, you can provide Sentiance with the list of geofences to configure.

Prerequisites

The Smart Geofences feature relies on additional library dependencies alongside the core SDK dependency. To start using this feature, you must first add these dependencies to you project.

iOS

This feature is included in the main SDK framework. No additional dependencies are needed.

Android

Open your app build.gradle file and add the smart geofences dependency.

app/build.gradle

dependencies {
    implementation(platform("com.sentiance:sdk-bom:<sentiance-version>"))
    implementation("com.sentiance:sdk-smart-geofences")
}

React Native

This feature is included after installing the following modules:

• @sentiance-react-native/core

• @sentiance-react-native/smart-geofences

Flutter

This feature can be added by installing the following packages:

• sentiance_core

• sentiance_smart_geofences

Utilize the Smart Geofences APIs

In this section, you’ll find examples showing how to subscribe for geofence entry and exit events, how to force-update the geofence list, and how to check the geofence monitoring status.

Listen to Smart Geofence Entry and Exit Events

Checkout Real-time Listeners to read more about implementing the SDK's Listeners

You can subscribe to receive geofence entry and exit event notification as they are detected.

iOS

// Create an instance of the delegate that will handle the events.
private let smartGeofenceEventDelegate = MySmartGeofenceEventDelegate()

// Set the delegate on the Sentiance SDK. Note that the SDK holds a weak
// reference to this delegate.
Sentiance.shared.smartGeofenceEventsDelegate = smartGeofenceEventDelegate

// Define the delegate class that will handle the events.
class MySmartGeofenceEventDelegate: SmartGeofenceEventDelegate {
    func onSmartGeofenceEvent(_ smartGeofenceEvent: SmartGeofenceEvent) {
        // Handle the events here.
    }
}

Android

import com.sentiance.sdk.smartgeofences.api.SmartGeofenceApi

SmartGeofenceApi.getInstance(mContext).setSmartGeofenceEventListener { event ->
    // Handle the events here.
}

React Native

To get smart geofence entry/exit event updates even when your app is in the background, place the following code inside your app's entrypoint index.js file. If you're only interested in these updates when your app is foregrounded, place this code inside the appropriate UI code instead.

import {addSmartGeofenceEventListener} from "@sentiance-react-native/smart-geofences";
import SentianceCore from "@sentiance-react-native/core";

await SentianceCore.ensureInitialized();

// If you're subscribing to event updates only in the foreground, make sure
// to call subscription.remove() inside your component's componentWillUnmount() function
const subscription = addSmartGeofenceEventListener(smartGeofenceEvent => {
    // Handle the events here.
});

Flutter

Create a background.dart file under your project's lib folder with the following code:

background.dart

import 'package:sentiance_smart_geofences/sentiance_smart_geofences.dart';
import 'package:sentiance_core/sentiance_core.dart';

@pragma('vm:entry-point')
void registerSmartGeofenceEventListener() async {
  WidgetsFlutterBinding.ensureInitialized();
  await SentianceCore.ensureInitialized();

  SentianceSmartGeofences.registerSmartGeofenceEventListener((smartGeofenceEvent) {
    // Handle the events here.
  });
}

Add the following code, depending on your target platform.

For iOS, add the following to your app delegate class:

AppDelegate.swift

import Flutter
import sentiance_smart_geofences

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {

    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
    
        // Other code
        
        // Make sure the SDK is initialized before calling this
        SentianceSmartGeofencesPlugin.initializeListener(
            withEntryPoint: "registerSmartGeofenceEventListener",
            libraryURI: "package:your_app_package_name/background.dart"
        )
        
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}

For Android, add this code to your custom application class:

MainApplication.kt

import android.app.Application
import com.sentiance.smart_geofences_plugin.SmartGeofencesPlugin

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // Other code

        val dartLibrary = "package:your_app_package_name/background.dart"
        // Make sure the SDK is initialized before calling this
        SmartGeofencesPlugin.initializeListener(this, dartLibrary, "registerSmartGeofenceEventListener")
    }
}

If you're calling other Smart Geofences plugin APIs or other 3rd party plugin APIs inside your registerSmartGeofenceEventListener Dart function, then you need to register these plugins with the Sentiance SDK. See this for more details.

Refresh the List of Monitored Geofences

The SDK regularly refreshes the list of monitored geofences. You can request an immediate refresh as follows:

iOS

Sentiance.shared.refreshSmartGeofences { result, error in
    if let result {
        print("Geofences refreshed")
    }
    if let error {
        print("Error happened with smart geofence refreshing:" + error.description)
    }
}

Android

import com.sentiance.sdk.smartgeofences.api.SmartGeofenceApi

SmartGeofenceApi.getInstance(mContext).refreshGeofences()
    .addOnSuccessListener {
        Log.d(TAG, "Geofences refreshed")
    }.addOnFailureListener {
        Log.d(TAG, "Failed to refresh geofences. Error: ${it.reason}")
    }

React Native

import {refreshGeofences} from "@sentiance-react-native/smart-geofences";

try {
     await refreshGeofences();
     console.log('Geofences refreshed');
} catch (error) {
     const refreshError = error.userInfo;
     console.error('Failed to refresh geofences. Error: ' + refreshError.reason);
}

Flutter

import 'package:sentiance_smart_geofences/sentiance_smart_geofences.dart';

final sentianceSmartGeofences = SentianceSmartGeofences();

void refreshGeofences() async {
  String result;

  try {
    await sentianceSmartGeofences.refreshGeofences();
    result = "Geofences refreshed successfully.";
  } on SmartGeofencesRefreshError catch (e) {
    result = "Failed to refresh geofences, reason: ${e.reason.name} - details: ${e.details}";
  } catch (e) {
    result = "An unexpected error occurred: $e";
  }

  print(result);
}

Get the Current Smart Geofences Detection Mode

You can check the smart geofences detection mode as follows:

iOS

let detectionMode = Sentiance.shared.smartGeofenceDetectionMode
print("Detection mode is:" + String(describing: detectionMode))

Android

val detectionMode = SmartGeofenceApi.getInstance(this).detectionMode
Log.d(TAG, "Detection mode is: $detectionMode")

React Native

import {getDetectionMode} from "@sentiance-react-native/smart-geofences";

const detectionMode = await getDetectionMode();
console.log('Detection mode is:', detectionMode);

Flutter

import 'package:sentiance_smart_geofences/sentiance_smart_geofences.dart';

final sentianceSmartGeofences = SentianceSmartGeofences();

void getDetectionMode() async {
  final detectionMode = await sentianceSmartGeofences.getDetectionMode();
  print('Detection mode is: $detectionMode');
}

When enabled, the detection mode can either be in the foreground (i.e when the app is visible), or both foreground and background, depending on the type of location permission that has been granted (i.e. "always" or "while-in-use").

When detection mode is disabled, it indicates a general issue with the SDK’s detection. You can check the SDK status to identify the cause.