What you will learn

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

What you will make

You will make a Notification Strategy that limits the number of beacon notifications.

To achieve this, the Notification Strategy will require a minium time between two beacon notifications.

Pre-requisites - What you need to get started

  • A Gitlab Account: the SDK is available through a private Gitlab. You must have received an email with your user account, including a link to create a password
  • Your SDK user information: in order to initialize the Mobile SDK, you must have received a Login, a Password and a Company name
  • A BLE beacon: a BLE beacon configured on your account is mandatory to test the application
  • An iOS Device: you need a compatible Bluetooth Low Energy iOS device that is able to detect beacons
  • The Xcode application: you must have downloaded Xcode from the App store
  • You must have completed the creating a beacon notification tutorial and the notification strategy 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 ios>beacon>8-Notification-Strategy>Starter project

Step 2: Configure the SDK

  • Configure your CocoaPod files, and .plist

  • In the AppDelegate, configure your SDK with:

    • the UUID of your beacon
    • the appropriate Adtag Environment
    • your login, password, and company details you received from Connecthings

If you need more information, take a look at the 5-minutes quickstart tutorial.

Step 3: Create a Notification Strategy

  • Create a BeaconNotificationStrategyFilter class in the project

  • Open the BeaconNotificationStrategyFilter.h file

  • Import the ATLocationBeacon package

#import <ATLocationBeacon/ATLocationBeacon.h>
  • The BeaconNotificationStrategyFilter.h must implement the ATBeaconNotificationStrategyDelegate delegate
@interface BeaconNotificationStrategyFilter : NSObject<ATBeaconNotificationStrategyDelegate>

@end 
  • Open the BeaconNotificationStrategyFIlter.m file

  • Implement the methods of the ATBeaconNoficationStrategyDelegate

@implementation BeaconNotificationStrategyFilter

-(bool) createNewNotification:(ATBeaconContent *)newBeaconContent feedStatus:(ATRangeFeedStatus)feedStatus{
    return false;
}

-(void) onNotificationIsCreated:(ATBeaconContent *)beconContent notificationStatus:(BOOL)notificationStatus{
    
}

-(bool) deleteCurrentNotification:(ATBeaconContent *)newBeaconContent feedStatus:(ATRangeFeedStatus)feedStatus{
    return false;
}

-(void) onNotificationIsDeleted:(ATBeaconContent *)beconContent notificationStatus:(BOOL)notificationStatus{}

-(void) onBackground{}

-(void) onForeground{}

-(void) onStartMonitoringRegion:(ATBeaconContent *)beaconContent feedStatus:(ATRangeFeedStatus)_feedStatus{}

-(void) load:(NSUserDefaults *)dataStore{}

-(void) save:(NSUserDefaults *)dataStore{}

@end

Step 4: Register the Notification Strategy

  • Open the AppDelegate.m file

  • In the didFinishLaunchingWithOptions method, register the BeaconNotificationStrategyFilter

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	[...]
    [self addNotificationStrategy:[[BeaconNotificationStrategyFilter alloc] init]];
    [...]
    
    return YES;
}

Step 5: Perform simple tests with the Notification Strategy

  • In the BeaconNotificationStrategyFilter.m file, the createNewNotification method returns false.
-(bool) createNewNotification:(ATBeaconContent *)newBeaconContent feedStatus:(ATRangeFeedStatus)feedStatus{
    return false;
}

Note:

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

-(bool) createNewNotification:(ATBeaconContent *)newBeaconContent feedStatus:(ATRangeFeedStatus)feedStatus{
    return true;
}

Note:

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

  • Look at the deleteCurrentNotification method. It returns false
-(bool) deleteCurrentNotification:(ATBeaconContent *)newBeaconContent feedStatus:(ATRangeFeedStatus)feedStatus{
    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 really the 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.h file
    • add a minTimeBetweenNotification parameter
    • declare a constructor with a minTimeBetweenNotification parameter.
@interface BeaconNotificationStrategyFilter : NSObject<ATBeaconNotificationStrategyDelegate>{
    long minTimeBetweenNotification;
}

-(id) initWithMinTimeBetweenNotification:(long)minTime;


@end
  • In the BeaconNotificationStrategyFilter.m file, implement the newly declared constructor
-(id) initWithMinTimeBetweenNotification:(long)minTime{
    self = [super init];
    if(self){
        minTimeBetweenNotification = minTime;
    }
    return self;
}
  • In the ApplicationDelegate.m file, update the BeaconNotificationStrategyFilter declaration, to set up a time span of 5 minutes between each notification:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [...]
    [self addNotificationStrategy:[[BeaconNotificationStrategyFilter alloc] initWithMinTimeBetweenNotification:5 * 60 * 1000]];
    [...]
}
  • Back in theBeaconNotificationStrategyFilter.h file, add a minNextTimeNotification parameter to define the next time that a beacon notification can be displayed.

Note:

The minNextTimeNotification is a critical parameter that must be restored after an application is killed and restarted.

This can be achieved using the load and save methods.
The SDK calls these methods at the best time and uses a DataStore to save the data.

  • In the BeaconNotificationStrategyFilter.h file, create a static MIN_NEXT_TIME_NOTIFICATION, which will be used as a key to save and load the minNextTimeNotification data.
#define MIN_NEXT_TIME_NOTIFICATION @"com.notification.minNextTimeNotification"

@interface BeaconNotificationStrategyFilter : NSObject<ATBeaconNotificationStrategyDelegate>{
    double minTimeBetweenNotification;
    double minNextTimeNotification;
}

Note:

Make sure that you choose a key that is truly unique because the DataStore is shared by all notification strategies.

  • In the BeaconNotificationStrategyFilter.m, implement the save and load methods in order to save and load the minNextTimeNotification parameter
-(void) load:(NSUserDefaults *)dataStore{
    minNextTimeNotification = [dataStore doubleForKey:MIN_NEXT_TIME_NOTIFICATION];
}

-(void) save:(NSUserDefaults *)dataStore{
    [dataStore setDouble:minNextTimeNotification forKey:MIN_NEXT_TIME_NOTIFICATION];
}
  • In the createNewNotification method, use the minNextTimeNotification parameter to define when the SDK is authorized to notify the application and let it create a notification.
-(bool) createNewNotification:(ATBeaconContent *)newBeaconContent feedStatus:(ATRangeFeedStatus)feedStatus{
    return minNextTimeNotification < CACurrentMediaTime();
}
  • 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.
-(bool) deleteCurrentNotification:(ATBeaconContent *)newBeaconContent feedStatus:(ATRangeFeedStatus)feedStatus{
    return true;
}
  • When the notification is created, update the minNextTimeNotification parameter in order it define the next time a notification can be displayed
-(void) onNotificationIsCreated:(ATBeaconContent *)beconContent notificationStatus:(BOOL)notificationStatus{
    if(notificationStatus){
        minNextTimeNotification = CACurrentMediaTime() + 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

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 Xcode, launch the installation of the application on your mobile phone.

  2. Put the application in the background

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

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

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

  6. Wait for the notification to be cancelled.

  7. Start your beacon again.

  8. Check that no notification is triggered again.