Geofencing service

Geofencing allows you to establish a virtual fence around a predefined geographic area. When one of your app users enters or exits the area, you can set your app to push a message to the user. Infobip IP Messaging Platform supports geolocation based campaigns. This guide explains how you can easily setup your iOS application to support geolocation-based campaigns.

Configuring project for using geofencing services

Include NSLocationWhenInUseUsageDescription and NSLocationAlwaysUsageDescription keys in your app’s Info.plist. These keys let you describe the reason your app accesses the user’s location information. The system includes the value of these keys in the alert panel displayed to the user when requesting permission to use location services.

Usage

MobileMessaging SDK has geofencing service disabled by default. The service starts up after the MobileMessaging.start() is called and the service will automatically prompt the user for permissions for the app to use iOS Location Services. The “Always” authorization level is requested by default for the sake of better monitoring accuracy.

Enabling the Geofencing service

In order to enable the Geofencing service, use the following code:

• In case you are starting MobileMessaging manually:

// Swift
MobileMessaging.withApplicationCode(<#your application code#>, notificationType: <#notification type#>).withGeofencingService.start()

// Objective-C
[[[MobileMessaging withApplicationCode: <#your application code#> notificationType: <#notification type#>] withGeofencingService] start: nil];

• In case you are inheriting your AppDelegate from MobileMessagingAppDelegate, you override geofencingServiceEnabled variable in your AppDelegate:

// Swift
override var geofencingServiceEnabled: Bool {
	return true
}

// Objective-C
-(BOOL)geofencingServiceEnabled {
    return YES;
}

Custom initialization and startup flow

In case you want to change the default authorization level or to implement your own initialization and launching flow the Geofencing service has a convenient API:

// Swift
MobileMessaging.geofencingService.authorize(.WhenInUse) { capabilityStatus in
    switch capabilityStatus {
    case .Authorized:
        // user has authorized the service, you are free to start using it
        MobileMessaging.geofencingService.start()
    case .Denied:
        // user denied the access for Location Service, you can try to talk him out of it :)
    case .NotAvailable:
        // the service is not available on the device, there is nothing you can do
    case .NotDetermined:
        break // a fairly unlikely scenario
    }
}

// Objective-C
[[MobileMessaging geofencingService] authorize: MMLocationServiceUsageWhenInUse completion:^(enum MMCapabilityStatus capabilityStatus) {
    switch (capabilityStatus) {
        case MMCapabilityStatusAuthorized:
            // user has authorized the service, you are free to start using it
            [[MobileMessaging geofencingService] start: nil];
            break;
        case MMCapabilityStatusDenied:
            // user denied the access for Location Service, you can try to talk him out of it :) #>
            break;
        case MMCapabilityStatusNotAvailable:
            // the service is not available on the device, there is nothing you can do #>
            break;
        case MMCapabilityStatusNotDetermined:
            // a fairly unlikely scenario
            break;
    }
}];

In order to stop the service:

// Swift
MobileMessaging.geofencingService.stop()

// Objective-C
[[MobileMessaging geofencingService] stop];

Region entered/left events

In order to be notified about the region entered/left events you subscribe to MMNotificationGeographicalRegionDidEnter and MMNotificationGeographicalRegionDidExit respectively:

//Swift
NSNotificationCenter.defaultCenter().addObserver(self,
                                                 selector: #selector(geographicalRegionEntered(_:)),
                                                 name: MMNotificationGeographicalRegionDidEnter,
                                                 object: nil)

NSNotificationCenter.defaultCenter().addObserver(self,
                                                 selector: #selector(geographicalRegionExited(_:)),
                                                 name: MMNotificationGeographicalRegionDidExit,
                                                 object: nil)

// Objective-C
[[NSNotificationCenter defaultCenter] addObserver: self
                                         selector: @selector(geographicalRegionEntered:)
                                             name: MMNotificationGeographicalRegionDidEnter
                                           object: nil];

[[NSNotificationCenter defaultCenter] addObserver: self
                                         selector: @selector(geographicalRegionExited:)
                                             name: MMNotificationGeographicalRegionDidExit
                                           object: nil];

The NSNotification object will contain the information about the region:

// Swift
func geographicalRegionEntered(notification: NSNotification) {
    guard let region = notification.userInfo?[MMNotificationKeyGeographicalRegion] as? MMRegion else
    {
        return
    }
    print("Region entered: \(region)")
    print("Campaign text: \(region.campaignText)")
    <# handle the event the way you like #>
}

// Objective-C
-(void)geographicalRegionEntered:(NSNotification *)notification {
    MMRegion * region = notification.userInfo[MMNotificationKeyGeographicalRegion];
    NSLog(@"Region entered: %@", region);
    NSLog(@"Campaign text: %@", region.campaignText);
    <# handle the event the way you like #>
}