Implement Location Messaging on Android

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

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

   To be compatible with the current version of the SDK, replace {currentSupportedVersion} with 21.0.1. This version of Google Play Services has been tested with the latest version of the SDK. Using other versions of this dependency can lead to unexpected behavior, as its compatibility isn't guaranteed.

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

3. Enable geofence messaging during SDK initialization.

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

4. To enable geofence messaging, request the required location permissions from your users at runtime. For users on devices running Android Q and above, request both the ACCESS_FINE_LOCATION and ACCESS_BACKGROUND_LOCATION permissions. For users on devices older than Android Q, 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.

5. Enable or disable geofence messaging at runtime. After the permission is granted, enable geofence messaging by calling enableGeofenceMessaging() at runtime.

   You can disable geofence messaging by calling disableGeofenceMessaging().

   MobilePush prevents your app from displaying a geofence message with an empty alert. If you include AMPscript in your message that returns no content or an empty string, the mobile app doesn’t display that message.

1. Add AltBeacon and Google Play Service Location dependencies to your build.

   To ensure compatibility with the current SDK, replace {currentBeaconVersion} with 2.20-beta1 and {currentLocationVersion} with 21.0.1. These versions have been thoroughly tested with the latest SDK version. Using other versions of these dependencies can lead to unexpected behavior, as their compatibility isn't guaranteed.

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

3. Enable beacon messaging during SDK initialization.

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

4. 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 running Android Q and above, request both the ACCESS_FINE_LOCATION and ACCESS_BACKGROUND_LOCATION permissions. For users on devices older than Android Q, you can 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 R and above, add request for BLUETOOTH_CONNECT. For users on devices running Android S and above, also request for BLUETOOTH_SCAN permission. For users on devices running Android 14 and above, 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.

5. Enable or disable beacon messaging at runtime. After all the permissions are granted, enable beacon messaging by calling enableProximityMessaging() at runtime.

   You can disable beacon messaging by calling disableProximityMessaging().

   MobilePush prevents the app from displaying a beacon message with an empty alert. If you include AMPscript in your message that returns no content or an empty string, the mobile app doesn't display that message.

To understand how beacons behave in different situations, see Beacon Messaging Scenarios.

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.