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.
To successfully use this functionality, your Marketing Cloud Engagement admin must enable your account with access to MobilePush and Location Services.
-
Add
Google Play Service Location
dependency to yourbuild.gradle
file.To be compatible with the current version of the SDK, replace
{currentSupportedVersion}
with21.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. -
Add the following permissions to your application’s
AndroidManifest.xml
. -
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.
-
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.
-
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.
-
Add
AltBeacon
andGoogle Play Service Location
dependencies to your build.To ensure compatibility with the current SDK, replace
{currentBeaconVersion}
with2.20-beta1
and{currentLocationVersion}
with21.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. -
Add the following permissions to your application’s
AndroidManifest.xml
. -
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.
-
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 App Permissions. For more information on requesting location updates, see Request location updates.
- 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
-
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.