What you will learn

This tutorial will teach you how to create a Notification Strategy.

Pre-requisites - What you need to get started

  • A Nexus Account: The SDK is available through a private Nexus. You must have received an email with your user account, including a link to create a password
  • Your SDK user information: To initialize the SDK, your should have received a User, a Password and a Company name.
  • A BLE beacon: A configured beacon on your account is mandatory to test the application
  • An Android Device: You need a compatible Bluetooth Low Energy Android device that is able to detect beacons
  • The Android Studio application: Android Studio must be downloaded from the Android Developpers’ website
  • You must have completed the creating a beacon notification tutorial and the notification strategies introduction tutorial

Step 1: Clone the beacon-tutorial repository

  • Clone the beacon-tutorial repository
git clone https://github.com/Connecthings/sdk-tutorial.git
  • Open the project android>beacon>8-Notification-Strategy>Starter with Android Studio

Step 2: Configure the SDK

  • Open the ApplicationNotification class
  • Configure the SDK with:
    • the UUID of your beacon
    • the appropriate Adtag Environment
    • your login, password, and company details you received from Connecthings

Step 3: Create a Notification Strategy

  • Create a BeaconNotificationStrategyFilter class in the project

  • The BeaconNotificationStrategyFilter must implement the BeaconNotificationStrategy interface

public class BeaconNotificationStrategyFilter implements BeaconNotificationStrategy {
    
    @Override
    public boolean deleteCurrentNotification(BeaconContent beaconContent, FEED_STATUS feed_status) {
        return false;
    }
@Override
    public boolean createNewNotification(BeaconContent beaconContent, FEED_STATUS feed_status) {
        return false;
    }

    @Override
    public void onNotificationCreated(boolean b, BeaconContent beaconContent) {

    }

    @Override
    public void onNotificationDeleted(boolean b, BeaconContent beaconContent, FEED_STATUS feed_status) {

    }

    @Override
    public void onStartMonitoringRegion(BeaconContent beaconContent, FEED_STATUS feed_status) {

    }

    @Override
    public void onBackground() {

    }

    @Override
    public void onForeground() {
    
    }
    
    @Override
    public void load(DataHolder data){
    
    }
    
    @Override
    public void save(DataHolder data){
    
    }
} 

Step 4: Register the Notification Strategy

  • Open the ApplicationNotification class

  • In the onCreate method, register the BeaconNotificationStrategyFilter in AdtagBeaconManager

 public void onCreate(){
        super.onCreate();
        [...]
        beaconManager.addNotificationStrategy(new BeaconNotificationStrategyFilter());
}

Step 5: Perform simple tests with the Notification Strategy

  • In the BeaconNotificationStrategyFilter class, the createNewNotification method returns false.
public boolean createNewNotification(BeaconContent beaconContent, FEED_STATUS feed_status) {
	return false;
}

Note:

This means that the Notification Strategy forbids the creation of any beacon notification.

public boolean createNewNotification(BeaconContent beaconContent, FEED_STATUS feed_status) {
	return true;
}

Note:

This means that the Notification Strategy authorizes the creation of all beacon notifications.

  • Look at the deleteCurrentNotification method. It returns false
public boolean deleteCurrentNotification(BeaconContent beaconContent, FEED_STATUS feed_status) {
	return false;
}

Note:

This means that the beacon notification will not be cancelled when the mobile phone exits the beacon's range.
If the notification is not cancelled, the SDK cannot display a new beacon notification.

As a consequence, in this example, only the first notification is displayed, and keeps being displayed until the user cancels it. If the user cancels the notification, no new beacon notification is displayed.

Step 6: Implement a real-life Notification Strategy

We suggest to continue the tutorial with the implementation of a Notification Strategy that limits the number of notifications a user will see, by defining a minimum time span between two beacon notifications.

  • In the BeaconNotificationStrategyFilter class, add a constructor with a minTimeBetweenNotification parameter.
public class BeaconNotificationStrategyFilter implements BeaconNotificationStrategy {

    private int minTimeBetweenNotification;

    public BeaconNotificationStrategyFilter(int minTimeBetweenNotification) {
        this.minTimeBetweenNotification = minTimeBetweenNotification;
    }
    [...]
}
  • In the ApplicationNotification class, update the BeaconNotificationStrategyFilter declaration, to set up a time span of 5 minutes between each notification:
public void onCreate(){
    super.onCreate();
    [...]
    beaconManager.addNotificationStrategy(new BeaconNotificationStrategyFilter(5* 60 * 1000));
}
  • Back in the BeaconNotificationStrategyFilter class, add a minNextTimeNotification parameter to define the next time that a beacon notification can be displayed.
public class BeaconNotificationStrategyFilter implements BeaconNotificationStrategy {
    
    private long minNextTimeNotification;
    private int minTimeBetweenNotification;

    public BeaconNotificationStrategyFilter(int minTimeBetweenNotification) {
        this.minTimeBetweenNotification = minTimeBetweenNotification;
    }
    [...]
}
  • Use the minNextTimeNotification parameter, in the createNewNotification method, to define when the SDK is authorized to notify the application about creating a notification.
  @Override
public boolean createNewNotification(BeaconContent beaconContent, FEED_STATUS feed_status) {
	return minNextTimeNotification < System.currentTimeMillis();
}
  • As the goal of this tutorial is only to limit the number of notifications a user can see, no change will be made to the default cancellation process. As such, the deleteCurrentNotification method must return true to let the SDK cancel the notification normally.
public boolean deleteCurrentNotification(BeaconContent beaconContent, FEED_STATUS feed_status) {
	return true;
}
  • Once the notification has been deleted, update the minNextTimeNotification parameter, in order to define when a new notification can be displayed
public void onNotificationDeleted(boolean b, BeaconContent beaconContent, FEED_STATUS feed_status) {
    if(b){
         minNextTimeNotification = System.currentTimeMillis() + minTimeBetweenNotification;
    }
}

Note 1:

Keep in mind that even if the specific Notification Strategy that you have just implemented always deletes the notification, this is not necessarily the case for all of the Notification Strategies that will be added to your application.

As a consequence:

  • do not update any parameters in the deleteCurrentNotification method because other strategies may require that the notification stay even when the phone exits the beacon's range
  • always do it through the onNotificationDeleted method after checking the deletion status.

Similarly, do not use the createBeaconNotification method to update parameters, but always use the onCreateBeaconNotification after checking the creation status.

Note 2:

The following methods allow you to update your notification strategy parameters for specific occasions:

  • onStartMonitoringRegion: when the SDK starts to monitor zone entries and exits for a specific beacon
  • onBackground: when the application switches from foreground to background
  • onForeground: when the application switches from background to foreground
  • The minNextTimeNotification variable must be saved and loaded in case the application is killed.
public class BeaconNotificationStrategyFilter implements BeaconNotificationStrategy {
  
  private static final String MIN_NEXT_TIME_NOTIFICATION = "com.tuto.notification.minNextTimeNotification";
  
  @Override
  public void save(DataHolder data){
    data.putLong(MIN_NEXT_TIME_NOTIFICATION, minNextTimeNotification);    
  }

  @Override
  public void load(DataHolder data){
    minNextTimeNotification = data.getLong(MIN_NEXT_TIME_NOTIFICATION, 0);
  }
} 

Note 1:

When the application is killed, the service that scans for beacons is automatically restarted.

Note 2:

The SDK call the save and load method when necessary.

Step 7: Start testing

If your beacon is already emitting, you must stop/restart the emission process in order to simulate a new region entry for the smartphone, and generate a notification.

There are 2 solutions to stop/restart the emission process:

  • You can put the beacon inside a microwave (but don't start it!)
  • You can remove the battery from the beacon (in that case, depending on the model, it can take up to 30 seconds for the beacon to start emitting again when you put the battery back)
  1. From Android Studio, launch the installation of the application on your mobile phone.

  2. On Android 6 and above, when the application starts, a popup asks for permission to access your phone location: grant it!

  3. Put the application in the background

  4. Remove the beacon from the microwave or put the battery back in the beacon.

  5. Wait for a few seconds (maximum 1 minute)

  6. Once the notification is displayed, remove the beacon's battery (or put the beacon back in the microwave)

  7. Wait for the notification to be cancelled.

  8. Start your beacon again.

  9. Check that no notification is triggered again.

Note:

On some phones with Android 6 and above, it is necessary to enable location on the phone for the beacons to be detected when the application is in the background.