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

1. Include the NSLocationAlwaysUsageDescription key in your app’s Info.plist file and set the value of that key to a string that describes how your app intends to use location data. These description will be displayed as part of the alert when the system prompts the user to allow access.

2. Specify device-related features required for the app to run.

   Note:

   If you don't need geofencing service supported for all devices on which your app can be installed, you can skip this step. But be aware that on devices which don't have gps capability, geofencing service can work with less accuracy.

   Include the UIRequiredDeviceCapabilities key in the app’s Info.plist file. The value for the UIRequiredDeviceCapabilities is an array of strings indicating the features that your app requires. Two strings are required for using geofencing services:

   • location-services
   • gps

   For more information about the UIRequiredDeviceCapabilities key, see Information Property List Key Reference.

3. For better accuracy of Geofencing service, you can specify "location" value of the UIBackgroundModes key. For doing it you should go to Capabilities tab of your Xcode project, enable the Background Modes capability and choose the Location updates mode.

Note:

If your application does not require persistent real-time location updates, please do not setup "location" setting from the UIBackgroundModes. For example applications that might need persistent geolocation tracking are fitness or turn-by-turn navigation apps. If you plan to submit your application to App Store, be aware that App Store Review team can ask about purposes of this type of location updating.

If you choose to setup "location" value of the UIBackgroundModes, do not forget to include the following battery use disclaimer in your Application Description: "Continued use of GPS running in the background can dramatically decrease battery life."

Usage

MobileMessaging SDK has geofencing service enabled 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.

Disabling the default Geofencing service startup

In order to disable the default Geofencing service startup procedure, use the following code:

• In case you are starting MobileMessaging manually:

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

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

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

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

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

Custom initialization and startup flow

Notice

If you prefer to authorize and start the Geofencing service by yourself, don't forget to disable the default Geofencing service startup procedure.

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 #>
}