What you will learn

AdTag allows you to manage several notification options, such as the maximum number the SDK can display over a given period of time, or the minimum time span between two notifications (see our AdTag Application Settings document for more information. Depending on your objectives with beacons, you may want to add specific filters to refine the exact conditions around notification display in your app – for instance, to match notifications with specific user profiles, or to enable users to activate/deactivate specific types of notifications based on their personal preferences. This is what we call Custom Notification Strategies. This tutorial will guide through their creation & registration process with our SDK, and give you simple, practical illustrations to start working with them.

Prerequisites - What you need to get started

  • Your SDK credentials, including an SDK Login, Password, and Company Key to initialize the SDK.
  • A BLE beacon, which has been configured on your account, in order to test interactions with your app.
  • An Android Device, with Bluetooth 4.0 and Android 4.0 and above, to be able to interact with BLE beacons.
  • The Android Studio application, which you can download from the Android Developers website.
  • You must have completed the notification creation tutorial, and read the introduction to notification strategies

Step 1: Clone the sdk-tutorial repository

  • Clone the sdk-tutorial repository
git clone https://github.com/Connecthings/sdk-tutorial.git
  • Open the project android>beacon>6-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 (DEMO / PREPROD / PROD / PROD_US)
    • your SDK credentials (your login, password, and company details from Connecthings )
      AdtagInitializer.initInstance(this)
                      .initUrlType(UrlType.DEMO / ... / UrlType.PROD)
                      .initUser("YOUR_USER",  "YOUR_PWD")
                      .initCompany("YOUR_COMPANY_KEY").synchronize();

If you need more informations, have a look to the 5 minutes quickstart tutorial

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 String getName() {
        return null;
    }

    @Override
    public void updateParamaters(JsonObject jsonObject) {

    }

    @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 created, BeaconContent beaconContent) {

    }

    @Override
    public void onNotificationDeleted(boolean deleted, 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 dataHolder) {

    }

    @Override
    public void save(DataHolder dataHolder) {

    }
}

Step 4: Register the Notification Strategy

  • First, define the key of your custom strategy. For example:
@Override
public String getName() {
    return "beaconNotificationStrategyFilter";
}
  • Open the ApplicationNotification class
  • In the onCreate method, register the BeaconNotificationStrategyFilter in AdtagBeaconManager
 public void onCreate(){
        super.onCreate();
        [...]
        AdtagBeaconManager.getInstance().registerNotificationStrategy(new BeaconNotificationStrategyFilter());
}

Step 5: Experiment with the Custom Notification Strategy

  • Experiment with the default configuration: 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 Custom Notification Strategy prevents the creation of any beacon notification.

  • You can launch the application to verify this, using the testing procedure described in the beacon notification creation tutorial
  • Now, make the createNewNotification method return true:
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, without any filter.

  • 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 Custom Notification Strategy

Let’s continue the tutorial with the implementation of a Custom 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();
    [...]
    AdtagBeaconManager.getInstance().registerNotificationStrategy(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 deleted, BeaconContent beaconContent, FEED_STATUS feed_status) {
    if (deleted) {
         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 stays, 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 entry region for your 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 after you reinsert the battery)
  1. In Android Studio, launch the installation of the application you have just built on your mobile phone.

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

  3. Close your application or leave it running in the background

  4. Remove the beacon from the microwave or reinsert the battery.

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

  6. Click on the notification that has appeared on your screen just for fun.

  7. Wait for the notification to be cancelled.

  8. Re-start your beacon

  9. Wait for 5 min and double-check that no notification appears

Note:

Some Android 6 and above smartphone models now need location to be activated in order to enable background beacon detection.