What you will learn:

By integrating our SDK, you can display Notifications on your app when a zone is detected nearby.

To make things easier, our SDK contains a default Auto Notification: this is a built-in notification that is automatically generated when a zone is detected nearby, as soon as the SDK has been initialized in your app.

You also have the ability to configure custom-built notifications, using our model of interfaces and built-in objects.

In both cases, you can manage the content of your local notifications directly on our Herow platform.

This tutorial tells you more about these Auto and custom-built local notifications, and how you can work with them.

Pre-requisites - What you need to get started

  • Your SDK credentials, including an SDK Login, Password, and Company Key to initialize the SDK.
  • A zone, which has been configured on your herow account.
  • An iOS Device, with Bluetooth 4.0 and iOs 9 and above.
  • The Xcode application, which you can download from the App store.
  • You must have completed the 5 minutes QuickStart Tutorial.

Initialize the SDK

Step 1: Clone the sdk-tutorial repository

  • Clone the sdk-tutorial repository
git clone https://github.com/Connecthings/sdk-tutorial.git

objectivec

  • Open the ios>ObjectiveC>Zone>2-Notification>Starter folder

SWIFT

  • Open the ios>SWIFT>Zone>2-Notification>Starter folder

Step 2: Configure the SDK

  • Configure your CocoaPod files and .plist
  • Configure your SDK with:
    • the appropriate Herow Environment ( PREPROD / PROD )
    • your SDK credentials

Switch to Swift

[[[[HerowInitializer sharedInstance] configPlatform: HerowPlatform.prod]
									 configUserWithLogin:@"your username"
									 password:@"your password"
									 company:@"your company"]
									 synchronize];

herowInitializer = HerowInitializer.shared
herowInitializer?.configPlatform(Platform.prod)
				 .configUser(login: "your username", password: "your password", company: "your company")
				 .synchronize()

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

Step 3: Enable your app to receive local Notifications

We invite you to read the 5 minutes QuickStart Tutorial to check the steps to receive the local Notifications.

Customize your Auto Notifications

As a reminder, Auto Notifications are notifications generated by default by the SDK. You can manage their content (text – title & description - , URI, and content image), and disable them if necessary, directly from the Herow platform, in the Application Settings section.

Attach a sound to an auto-notification

  • add a new property list file (pList) to the supporting file folder of your project

  • Name it connectplace-settings

  • add the property notificationSoundAuthorized as Boolean, and set it to true

  • If you would like to attach a specific sound to a notification, add the property notificationSoundFile as String, and specify the notification sound name.

Note: Be sure to have authorized your application to receive sound notification when configuring the notification settings of your app. For example:

Switch to Swift

 UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
 [center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert | UNAuthorizationOptionSound) completionHandler:^(BOOL granted, NSError * _Nullable error) {  
 }];
 let center = UNUserNotificationCenter.current()
 center.requestAuthorization(options: [.alert, .sound]) { (granted, error) in }

Create custom-built notifications

If you would like to implement notifications that are more customizable than our Auto notifications, you can replace them with your own, custom-built, local notifications, as described in the following section.

Notification Model Overview

First, let’s go through an overview of the notification model, with the corresponding interfaces and built-in objects.

The HerowNotificationTask

The HerowNotificationTask is a delegate that allows your application to complete an asynchronous task of your choice before displaying a notification. A default implementation of this delegate is available. It's the NotificationImageTask: it directly downloads the notification image from Herow, and when ready displays the notification with the corresponding image.

The method launchNotificationTask takes two parameters:

  • herowPlaceNotification: the common object used by the SDK to deal with notification which contains Herow data
  • displayPlaceNotificationListener: the object used to notify the SDK when the notification is ready to be displayed

The DisplayPlaceNotificationListener

The DisplayPlaceNotificationListener is an interface that is mainly in charge of displaying the notification linked with a zone. Before a notification is triggered, the NotificationManager checks that the corresponding zone is still within range. If so, the notification is displayed; otherwise, nothing appears to the end user. To notify the NotificationManager of the need to display a notification, you must call the displayPlaceNotification method, which takes a PlaceNotificationImage object as argument.

The NotificationBuilder

The NotificationBuilder interface allows you to create and customize your notifications.

If you want to create and use your own builder, you need to implement these two methods:

  • generateNotificationForIOS10AndPlus: use this function to generate and return an UNMutableNotificationContent, the method takes one argument - a PlaceNotificationImage.
  • generateNotificationForIOS9AndMinus: use this function to generate and return a UILocalNotification, the method takes one argument - a PlaceNotificationImage.

PlaceNotificationImage

A PlaceNotificationImage has 3 additional methods compared to the PlaceNotification object:

  • getImage: returns the bitmap associated with the notification image on Herow
  • hasImage: returns true if the image bitmap is available
  • isWelcomeNotification: returns true if the associated placeNotification is a welcome notification

What can you customize ?

Two of the previous interfaces can permit you to customize the notification process:

  • The HerowNotificationTask, which allows to associate additional content to the notification in an asynchronous way (as bitmap). This option will not be discussed in this document, but you can find a basic implementation to help you start in the notification demo code folder.
  • The NotificationBuilder, which allows to have a full control on the notification content and parameters. The next step will develop an implementation of the NotificationBuilder interface.

Step 1: Create your own NotificationBuilder

  • Create a new class named MyZoneNotificationBuilder
  • In the MyZoneNotificationBuilder.h file, implement the NotificationBuilder

Switch to Swift

#import <Foundation/Foundation.h>
#import <UserNotifications/UserNotifications.h>
@import ConnectPlaceActions;
@import HerowLocationDetection;
@import HerowConnection;


@interface MyZoneNotificationBuilder : NSObject <NotificationBuilder> {

}

@end
import Foundation
import UserNotifications
import ConnectPlaceActions
import HerowLocationDetection

class MyZoneNotificationBuilder: NSObject, NotificationBuilder {

}
  • Declare the generateNotificationForIOS10AndPlus method and the generateNotificationForIOS9AndMinus method in the MyZoneNotificationBuilder.m file

Switch to Swift


#define SYSTEM_VERSION_GREATER_THAN(v) ([[[UIDevice currentDevice] systemVersion] compare:v options:NSNumericSearch] == NSOrderedDescending)

@implementation MyZoneNotificationBuilder

- (UNMutableNotificationContent * _Nonnull)generateNotificationForIOS10AndPlusWithPlaceNotificationImage:(PlaceNotificationImage * _Nonnull) placeNotificationImage {

}

- (UILocalNotification * _Nonnull)generateNotificationForIOS9AndMinusWithPlaceNotificationImage:(PlaceNotificationImage * _Nonnull)placeNotificationImage {

}

@end
func generateNotificationForIOS10AndPlus(placeNotificationImage: PlaceNotificationImage) -> UNMutableNotificationContent {

}

func generateNotificationForIOS9AndMinus(placeNotificationImage: PlaceNotificationImage) -> UILocalNotification {

}

Step 2: Generate the local notification

  • Generate your notification based on the IOS version:

Switch to Swift

- (UNMutableNotificationContent * _Nonnull)generateNotificationForIOS10AndPlusWithPlaceNotificationImage:(PlaceNotificationImage * _Nonnull) placeNotificationImage {
    UNMutableNotificationContent *notificationContent = [[UNMutableNotificationContent alloc] init];

    HerowPlaceNotification *placeNotification = [placeNotificationImage getPlaceNotification];

    if([placeNotification getDescription].length <= 0) {
        notificationContent.body = [placeNotification getTitle];
    }else{
        notificationContent.body = [placeNotification getDescription];
    }
    if([placeNotification getTitle].length > 0) {
        notificationContent.title = [placeNotification getTitle];
    }

    if (placeNotificationImage.hasImage) {
        UNNotificationAttachment *attachement1 = [UNNotificationAttachment attachmentWithIdentifier:@"com.connecthings.zoneNotificationImage" URL:placeNotificationImage.getImageURL options:nil error:nil];
        notificationContent.attachments=@[attachement1];
    }

    return notificationContent;
}

- (UILocalNotification * _Nonnull)generateNotificationForIOS9AndMinusWithPlaceNotificationImage:(PlaceNotificationImage * _Nonnull)placeNotificationImage {
    NSLog(@"create notification from app delegate");
    UILocalNotification *notification = [[UILocalNotification alloc]init];

    HerowPlaceNotification *placeNotification = [placeNotificationImage getPlaceNotification];

    if ([placeNotification getDescription].length <= 0) {
        [notification setAlertBody:[placeNotification getTitle]];
    } else{
        [notification setAlertBody:[placeNotification getDescription]];
    }

    if (SYSTEM_VERSION_GREATER_THAN(@"7.99") && [placeNotification getTitle].length > 0) {
        [notification setAlertTitle:[placeNotification getTitle]];
    }

    return notification;
}
func generateNotificationForIOS10AndPlus(placeNotificationImage: PlaceNotificationImage) -> UNMutableNotificationContent {
    let placeNotification = placeNotificationImage.getPlaceNotification()
    let notificationContent: UNMutableNotificationContent = UNMutableNotificationContent()

    notificationContent.title = placeNotification.getTitle()
    if placeNotification.getDescription().isEmpty {
        notificationContent.body = placeNotification.getTitle()
    } else {
        notificationContent.body = placeNotification.getDescription()
    }

    if placeNotificationImage.hasImage() {
        do {
            let notificationId = "com.connecthings.zone.image"
            if let imageURL = placeNotificationImage.getImageURL() {
                let attachement: UNNotificationAttachment! = try UNNotificationAttachment.init(identifier: notificationId, url: imageURL, options: nil)
                notificationContent.attachments = [attachement]
            }
        } catch _{}
    }
    return notificationContent
}

func generateNotificationForIOS9AndMinus(placeNotificationImage: PlaceNotificationImage) -> UILocalNotification {
    let placeNotification = placeNotificationImage.getPlaceNotification()
    let localNotification: UILocalNotification = UILocalNotification()

    let kLocalNotificationTitle:String! = placeNotification.getTitle()
    let kLocalNotificationMessage:String! = placeNotification.getDescription()

    localNotification.alertTitle = kLocalNotificationTitle
    if kLocalNotificationMessage?.isEmpty == false {
        localNotification.alertBody = kLocalNotificationTitle
    } else {
        localNotification.alertBody = kLocalNotificationMessage
    }

    return localNotification
}

Note:

The PlaceNotificationImage object contains the content associated with the zone in Herow, moreover it can also contain the image downloaded thanks to the NotificationTask. To access the content, you can use the method getPlaceNotification() which returns an interface with the following main methods :

  • getTitle(): retrieves the title of the notification
  • getDescription(): retrieves the description of the notification

The SDK possesses an implementation of the PlaceNotification called HerowPlaceNotification, which contains an HerowContent object. Through it, you can also base the text of your notification on other Herow categories & fields of your choice, using the method herowContent getValueFromCategory.

For example, herowContent getValueFromCategory:@"LINE" andField:@"DIRECTION" allows you to retrieve the DIRECTION field of the LINE category for a real-time transit schedule use case.

Step 3: Register your MyNotificationBuilder

  • Open the AppDelegate.m file
  • First initialize the SDK
  • Get an instance of the HerowDetectionManager class and register an instance of our MyNotificationBuilder class thanks to the method registeNotificationBuilder()

Switch to Swift

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [...]
    [[HerowDetectionManager shared] registerEnterNotificationBuilder: [[MyZoneNotificationBuilder alloc] init]];
    [...]
    return YES;
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    [...]
    HerowDetectionManager.shared.registerEnterNotificationBuilder(MyZoneNotificationBuilder())
    [...]
}

Note:

The HerowDetectionManager only accepts one NotificationBuilder.

In other words, if you register a new NotificationBuilder, the existing one will be automatically replaced.

Start testing

Refer to our quick start tutorial to test the project