Add Beacons

Use the Salesforce Engagement SDK to trigger proximity-based notifications when users come near Bluetooth beacons. Follow these steps to add beacon support to your Android app.

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 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 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 with the configuration shown in these examples.

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

For SDK version 8, use this example.

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}

For SDK version 7, use this example.

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 SDK, see Troubleshoot Initialization Errors.

Important

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 earlier versions of Android, request only the ACCESS_FINE_LOCATION 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

After all the permissions are granted, enable beacon messaging by calling enableProximityMessaging() at runtime. Alternatively, call disableProximityMessaging() to disable beacon messaging.

For SDK version 10 or higher, use this example.

1MarketingCloudSdk.requestSdk {
2  it.regionMessageManager.enableProximityMessaging()
3
4  // Disable beacon messaging
5  // it.regionMessageManager.disableProximityMessaging()
6}

For SDK version 8, use this example.

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

For SDK version 7, use this example.

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.