Add Geofences

Enable geofence messaging to trigger location-based notifications when users cross geofence boundaries. Follow these steps to add geofence support to your Android app.

Add Dependencies

Add Google Play Service Location dependency to your build.gradle file.

1dependencies {
2   implementation 'com.google.android.gms:play-services-location:{currentSupportedVersion}'
3}

To be compatible with the current version of the SDK, replace {currentSupportedVersion} with 21.0.1. The SDK has been tested using this version of Google Play Services. Compatibility with other versions isn’t guaranteed.

Important

Add Permissions

Add these permissions to your application’s AndroidManifest.xml.

1<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
2<!-- ACCESS_BACKGROUND_LOCATION is required for geofence messaging feature on devices that run Android 10 or later. -->
3<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
4
5<!-- Boot complete is needed so that the SDK can reregister Geofences after a reboot -->
6<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
7<!-- Devices without GPS will not work with Geofence messaging -->
8<uses-feature android:name="android.hardware.location.gps" android:required="false" />

Enable During SDK Initialization

Enable geofence messaging during SDK initialization with the configuration shown in these examples.

SDK v10+

For SDK version 10 or higher, use this example.

1SFMCSdk.configure(applicationContext as Application, SFMCSdkModuleConfig.build {
2  engagementModuleConfig = MarketingCloudConfig.builder().apply {
3    // Other configuration values
4    setGeofencingEnabled(true) // Enable Geofence messaging, default = false
5  }.build(applicationContext)
6}) {
7  // Handle initialization status
8}

SDK v8

For SDK version 8, use this example.

1SFMCSdk.configure(applicationContext as Application, SFMCSdkModuleConfig.build {
2  pushModuleConfig = MarketingCloudConfig.builder().apply {
3    // Other configuration values
4    setGeofencingEnabled(true) // Enable Geofence messaging, default = false
5  }.build(applicationContext)
6}) {
7  // TODO handle initialization status
8}

SDK v7

For SDK version 7, use this example.

1MarketingCloudSdk.init(applicationContext as Application, with(MarketingCloudConfig.builder()) {
2  // Other configuration values
3  setGeofencingEnabled(true) // Enable Geofence messaging, default = false
4  build(applicationContext)
5}) {
6  // TODO Handle initialization status
7}

To troubleshoot information related to geofence messaging, examine the InitializationStatus returned during the initialization call for the SDK. See Troubleshoot Initialization Errors.

Important

Request Location Permissions

To enable geofence messaging, request the required location permissions from your users at runtime. For users on devices that run Android 10 or later, request both the ACCESS_FINE_LOCATION and ACCESS_BACKGROUND_LOCATION permissions. For users on devices older than Android 10, you can request only the ACCESS_FINE_LOCATION permission.

For more information on requesting location updates, see Request location updates. For information on requesting runtime permissions, see Request runtime permissions.

Note

Enable or Disable at Runtime

After the permission is granted, enable geofence messaging by calling enableGeofenceMessaging() at runtime. Alternatively, call disableGeofenceMessaging() to disable geofence messaging.

SDK v10+

For SDK version 10 or higher, use this example.

1MarketingCloudSdk.requestSdk {
2  it.regionMessageManager.enableGeofenceMessaging()
3
4  // Disable geofence messaging
5  //it.regionMessageManager.disableGeofenceMessaging()
6}

SDK v8

For SDK version 8, use this example.

1SFMCSdk.requestSdk { sdk ->
2  sdk.mp {
3    it.regionMessageManager.enableGeofenceMessaging()
4
5    // Disable geofence messaging
6    //it.regionMessageManager.disableGeofenceMessaging()
7  }
8}

SDK v7

For SDK version 7, use this example.

1MarketingCloudSdk.requestSdk { sdk ->
2  sdk.regionMessageManager.enableGeofenceMessaging()
3
4  // Disable geofence messaging
5  //sdk.regionMessageManager.disableGeofenceMessaging()
6}

The SDK suppresses geofence messages with no content. If you include AMPscript or a merge field in your message that returns an empty string, your app doesn’t display that message to the user.

Important