What you will learn

Herow allows you to manage several notification options, such as the maximum number of notifications the SDK can display over a given period of time, or the minimum time span between two notifications.

Depending on your objectives with zones, 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 Filters. This tutorial will guide you 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

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>zone>2-Notification>Starter with Android Studio

Step 2: Configure the SDK

  • Open the ApplicationNotification class
  • Configure the SDK with:
    • the appropriate Herow Environment ( usually PROD )
    • your SDK credentials (your SDK ID and SDK Key details from HEROW)
HerowInitializer.getInstance()
				.initInstance(this)
				.initUrlType(UrlType.PROD)
				.initApp("YOUR_SDK_ID",  "YOUR_SDK_KEY")
				.synchronize();

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

Step 3: Create a Notification filter

  • Create a MyNotificationFilter class in the project
  • The MyNotificationFilter must extend the BaseNotificationFilter class
public class MyNotificationFilter extends BaseNotificationFilter {
    @Override
    public String getName() {
        return null;
    }

    @Override
    public boolean deleteCurrentNotification(@NonNull PlaceNotification placeNotification) {
        return false;
    }

    @Override
    public boolean createNewNotification(@NonNull PlaceNotification placeNotification) {
        return false;
    }

    @Override
    public void onNotificationCreated(@NonNull PlaceNotification placeNotification, boolean b) {

    }

    @Override
    public void onNotificationDeleted(PlaceNotification placeNotification, boolean deleted) {

    }

    @Override
    public void onBackground() {

    }

    @Override
    public void onForeground() {

    }

    @Override
    public void load(@NonNull DataHolder dataHolder) {

    }

    @Override
    public void save(@NonNull DataHolder dataHolder) {

    }

    @Override
    public void updateParameters(@NonNull Object o) {

    }
    
    @Override
    public void reset() {
    
    }
}

Step 4: Register the Notification Filter on Herow

  • First, define the key of your custom filter. For example:
@Override
public String getName() {
    return "myNotificationFilterKey";
}
  • Open the ApplicationQuickStart class
  • In the onCreate method, register the MyNotificationFilter on the HerowZonesnManager
 public void onCreate(){
        super.onCreate();
        [...]
        HerowDetectionManager.getInstance().addNotificationFilter(new MyNotificationFilter());
}

Step 5: Experiment with the Custom Notification Filter

  • Experiment with the default configuration: in the MyNotificationFilter class, the createNewNotification method returns false.
public boolean createNewNotification(@NonNull PlaceNotification placeNotification) {
    return false;
}

Note:

This means that the Custom Notification Filter prevents the creation of any notification.

  • You can launch the application to verify this, using the testing procedure described in the zone notification creation tutorial
  • Now, make the createNewNotification method return true:
public boolean createNewNotification(@NonNull PlaceNotification placeNotification) {
    return true;
}

Note:

This means that the Notification Filter authorizes the creation of all notifications, without any filter.

  • Look at the deleteCurrentNotification method. It returns false:
public boolean deleteCurrentNotification(@NonNull PlaceNotification placeNotification) {
    return false;
}

Note:

This means that the notification will not be cancelled when the mobile phone exits the zones's range. If the notification is not cancelled, the SDK cannot display a new 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 notification is displayed.

Step 6: Implement a real-life Custom Notification Filter

Let’s continue the tutorial with the implementation of a Custom Notification Filter that limits the number of notifications a user will see, by defining a minimum time span between two notifications.

  • In the MyNotificationFilter class, add a constructor with a minTimeBetweenNotification parameter.
public class MyNotificationFilter extends BaseNotificationFilter {
    private int minTimeBetweenNotification;

    public MyNotificationFilter(int minTimeBetweenNotification) {
        this.minTimeBetweenNotification = minTimeBetweenNotification;
    }
    [...]
}
  • In the ApplicationQuickStart class, update the MyNotificationFilter declaration, to set up a time span of 5 minutes between each notification:
public void onCreate(){
    super.onCreate();
    [...]
    HerowDetectionManager.getInstance().addNotificationFilter(new MyNotificationFilter(5 * 60 * 1000));
}
  • Back in the MyNotificationFilter class, add a minNextTimeNotification parameter to define the next time that a notification can be displayed.
public class MyNotificationFilter extends BaseNotificationFilter {
    private long minNextTimeNotification;
    private int minTimeBetweenNotification;

    public MyNotificationFilter(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(@NonNull PlaceNotification placeNotification) {
    return minTimeBetweenNotification < 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.
@Override
public boolean deleteCurrentNotification(@NonNull PlaceNotification placeNotification) {
    return true;
}
  • Once the notification has been deleted, update the minNextTimeNotification parameter, in order to define when a new notification can be displayed
@Override
public void onNotificationDeleted(@NonNull PlaceNotification placeNotification, boolean deleted) {
    if (deleted) {
         minNextTimeNotification = System.currentTimeMillis() + minTimeBetweenNotification;
    }
}

Note 1:

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

As a consequence:

  • do not update any parameters in the deleteCurrentNotification method because other filters may require that the notification stays, even when the phone exits the zone's range
  • always do it through the onNotificationDeleted method after checking the deletion status.
  • similarly, do not use the createNewNotification method to update parameters, but always use the onNotificationCreated after checking the creation status.

Note 2:

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

  • 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 MyNotificationFilter extends BaseNotificationFilter {
    private static final String MIN_NEXT_TIME_NOTIFICATION = "com.tuto.notification.minNextTimeNotification";

    @Override
    public void save(@NonNull DataHolder dataHolder) {
        dataHolder.putLong(MIN_NEXT_TIME_NOTIFICATION, minNextTimeNotification);
    }

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

Note 1:

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

Note 2:

The SDK call the save and load method when necessary.

Step 7: Start testing

Refer to our quick start tutorial to test the project

Note:

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