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.

  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. The SDK has been tested using this version of Google Play Services. Compatibility with other versions isn’t guaranteed.

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

  3. Enable geofence messaging during SDK initialization. If you use version 10 of the SDK, use this code.

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

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

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

  4. 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.

  5. 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 of the SDK, use this code.

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

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

    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.

  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 tested with the latest SDK version. Other versions of these dependencies aren’t guaranteed to be compatible, which can lead to unexpected behavior.

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

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

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

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

    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.

  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 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.

  5. 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 of the SDK, use this code.

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

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

    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.

For information about 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.