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
- Your SDK credentials, including an SDK ID and SDK Key on HEROW to initialize the SDK.
- A zone, which has been configured on your herow account.
- 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 filters
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.
- You can launch the application to verify this, using the testing procedure described in the notification creation tutorial
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.