Implement Location Messaging on Android

The MobilePush SDK for Android uses the location capabilities of your customer’s device to trigger location-based notifications. The SDK caches geofence messages and displays them when a device crosses a geofence boundary. To implement location messaging, you must obtain user permission for location services.

To successfully use this functionality, your Marketing Cloud Engagement admin must enable your account with access to MobilePush and Location Services.

Add Geofences

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 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 geofence messaging during SDK initialization. If you use version 10 or higher of the SDK, use this code.

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}

If you use version 8 of the SDK, use this code.

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}

If you use version 7 of the SDK, use this code.

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 SDK’s initialization call. See Troubleshoot Initialization Errors.

Important

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 geofence messaging at runtime. After the permission is granted, enable geofence messaging by calling enableGeofenceMessaging() at runtime. Alternatively, call disableGeofenceMessaging() to disable geofence messaging.

If you use version 10 or higher of the SDK, use this code.

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

If you use version 8 of the SDK, use this code.

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

If you use version 7 of the SDK, use this code.

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

Add Beacons

Add AltBeacon and Google Play Service Location dependencies to your build.
1dependencies { 2 implementation 'com.google.android.gms:play-services-location:{currentLocationVersion}' 3 implementation 'org.altbeacon:android-beacon-library:{currentBeaconVersion}' 4}
To ensure compatibility with the current SDK, replace {currentBeaconVersion} with 2.20-beta1 and {currentLocationVersion} with 21.0.1. These versions have been tested with the latest SDK version. Other versions of these dependencies aren’t guaranteed to be compatible, which can lead to unexpected behavior.
Important

Add the following permissions to your application’s AndroidManifest.xml.

1<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
2<!-- ACCESS_BACKGROUND_LOCATION is required for Proximity messaging feature on Q & above devices. -->
3<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
4
5<!-- Boot complete is needed so that the SDK can reregister Beacons after a reboot -->
6<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
7
8<!-- BLUETOOTH_SCAN is needed so that the SDK can scan for nearby Beacons on S devices -->
9<uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>

Enable beacon messaging during SDK initialization. If you use version 10 or higher of the SDK, use this code.

1SFMCSdk.configure(applicationContext as Application, SFMCSdkModuleConfig.build {
2  engagementModuleConfig = MarketingCloudConfig.builder().apply {
3    // Other configuration values
4    setProximityNotificationOptions(
5      // Required config to show foreground notification
6      ProximityNotificationCustomizationOptions.create(R.mipmap.ic_notification_foreground)
7    )
8    setProximityEnabled(true) // Enable Beacon messaging, default = false
9  }.build(applicationContext)
10}) {
11  // Handle initialization status
12}

If you use version 8 of the SDK, use this code.

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

If you use version 7 of the SDK, use this code.

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

To troubleshoot information related to beacon messaging, examine the InitializationStatus returned during the SDK’s initialization call. For more information about troubleshooting the MobilePush SDK, see Troubleshoot Initialization Errors.

Important

Request location and Bluetooth permissions.
- Location permissions: To enable proximity messaging, request the required location permissions from your users at runtime. For users on devices that run Android 10 and later, request both the ACCESS_FINE_LOCATION and ACCESS_BACKGROUND_LOCATION permissions. For users with devices that run Android 10 or earlier, request only the ACCESS_FINE_LOCATION permission.
- Bluetooth permission: To enable proximity messaging, request the required location permissions from your users at runtime. For users on devices running Android 11 and later, add request for BLUETOOTH_CONNECT. For users on devices running Android 12 and later, also request for BLUETOOTH_SCAN permission. For users on devices that run Android 14 and later, also request for FOREGROUND_SERVICE.
For information on requesting runtime permissions, see Request runtime permissions. For more information on requesting location updates, see Request location updates.
Note
Enable or disable beacon messaging at runtime. After all the permissions are granted, enable beacon messaging by calling enableProximityMessaging() at runtime. Alternatively, call disableProximityMessaging() to disable beacon messaging.

If you use version 10 or higher of the SDK, use this code.
10.x or higher
1MarketingCloudSdk.requestSdk { 2 it.regionMessageManager.enableProximityMessaging() 3 4 // Disable beacon messaging 5 // it.regionMessageManager.disableProximityMessaging() 6}
If you use version 8 of the SDK, use this code.
8.x
1SFMCSdk.requestSdk { sdk -> 2 sdk.mp { 3 it.regionMessageManager.enableProximityMessaging() 4 5 // Disable beacon messaging 6 // it.regionMessageManager.disableProximityMessaging() 7 } 8}
If you use version 7 of the SDK, use this code.
7.x
1MarketingCloudSdk.requestSdk { sdk -> 2 sdk.regionMessageManager.enableProximityMessaging() 3 4 // Disable beacon messaging 5 // sdk.regionMessageManager.disableProximityMessaging() 6}
The SDK suppresses beacon messages that don’t contain any 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

For information about how beacons behave in different situations, see Salesforce Help: MobilePush Beacon Scenarios.

Enable Debug Logging for Beacons

Proximity logging is disabled by default. You can enable it using AltBeacon’s LogManager class.

The following is an example depicts how to enable debug logging for beacons using LogManager. The AltBeacon logger implementation in this example routes its logs through the Engagement MCLogListener interface.

1// Enable verbose logging from AltBeacon
2// This is very noisy and should only be done when an issue occurs.
3LogManager.setVerboseLoggingEnabled(true);
4
5// Pipe AltBeacon’s logs through the MarketingCloud MCLogListener interface.
6// This will adhere to the log level set by MarketingCloudSdk.setLogLevel()
7LogManager.setLogger(BeaconLogger())
8
9// You can also implement your own AltBeacon Logger
10LogManager.setLogger(object:Logger {})